# Provider Setup

Provider packs let a webhook accept signed events from Stripe, GitHub, Clerk, Slack, and Resend before the event reaches your agent or destination. Each pack uses the normal Hooksbase ingest URL, adds provider signature verification, and stamps provider metadata onto the accepted delivery.

## Shared setup model

Provider packs are a Starter+ workflow. The public ingest URL stays the same:

```text
https://api.hooksbase.com/v1/ingest/{publicId}
```

Two independent checks happen on provider-aware ingest:

1. Hooksbase checks `Authorization: Bearer whsec_...`.
2. Hooksbase verifies the provider signature headers against the provider pack secret.

If the provider dashboard cannot send the Hooksbase bearer header, place a small forwarder in front of Hooksbase. The forwarder must preserve the exact raw body and provider signature headers, then add `Authorization: Bearer whsec_...` before forwarding the request to Hooksbase.

**Create a provider-aware webhook**

```bash
curl https://api.hooksbase.com/v1/webhooks \
  -H "Authorization: Bearer swk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Stripe billing events",
    "providerSource": {
      "provider": "stripe",
      "config": {
        "signingSecret": "whsec_..."
      }
    },
    "defaultDestination": {
      "type": "webhook",
      "config": {
        "url": "https://agent.example.com/events"
      }
    }
  }'
```

## Stripe

Use the Stripe pack for signed JSON events such as `payment_intent.succeeded`, `invoice.payment_failed`, and `customer.subscription.updated`.

| Field | Value | | --- | --- | | Pack id | `stripe` | | Supported content type | `application/json` | | Required pack secret | `signingSecret` | | Required provider header | `stripe-signature` | | Challenge behavior | None |

Setup flow:

1. Create or edit a Hooksbase webhook with `providerSource.provider = "stripe"`.
2. Store the Stripe endpoint signing secret as `providerSource.config.signingSecret`.
3. Configure Stripe to send JSON webhook events to the Hooksbase ingest URL, or to a forwarder that adds the Hooksbase ingest bearer header.
4. Route on `provider.eventType` when different Stripe event types need different destinations.

Stripe metadata on accepted deliveries includes the Stripe event id, event type, API version, creation time, livemode flag, and nested object id when present.

## GitHub

Use the GitHub pack for signed repository and organization webhook events such as `push`, `pull_request`, and `issues`.

| Field | Value | | --- | --- | | Pack id | `github` | | Supported content type | `application/json` | | Required pack secret | `secret` | | Required provider headers | `x-hub-signature-256`, `x-github-delivery`, `x-github-event` | | Challenge behavior | None |

Setup flow:

1. Create or edit a Hooksbase webhook with `providerSource.provider = "github"`.
2. Store the GitHub webhook secret as `providerSource.config.secret`.
3. Configure GitHub to send JSON events to the Hooksbase ingest URL, or to a forwarder that adds the Hooksbase ingest bearer header.
4. Use `provider.sourceId` for GitHub delivery ids and `provider.eventType` for GitHub event names.

GitHub metadata on accepted deliveries includes the delivery id, event name, action, repository full name, and installation id when present.

## Clerk

Use the Clerk pack for Svix-signed JSON events such as `user.created`, `organization.created`, and `session.created`.

| Field | Value | | --- | --- | | Pack id | `clerk` | | Supported content type | `application/json` | | Required pack secret | `signingSecret` | | Required provider headers | `svix-id`, `svix-timestamp`, `svix-signature` | | Challenge behavior | None |

Setup flow:

1. Create or edit a Hooksbase webhook with `providerSource.provider = "clerk"`.
2. Store the Clerk signing secret as `providerSource.config.signingSecret`.
3. Configure Clerk to send JSON events to the Hooksbase ingest URL, or to a forwarder that adds the Hooksbase ingest bearer header.
4. Use `provider.eventType` to split user, organization, or session events across destinations.

Clerk metadata on accepted deliveries includes the Svix message id, event type, object type, and nested data id when present.

## Slack

Use the Slack pack for signed Slack events, interactions, and slash-command traffic. Slack is the only current pack that can return a synchronous challenge response instead of creating a delivery.

| Field | Value | | --- | --- | | Pack id | `slack` | | Supported content types | `application/json`, `application/x-www-form-urlencoded` | | Required pack secret | `signingSecret` | | Required provider headers | `x-slack-request-timestamp`, `x-slack-signature` | | Challenge behavior | `url_verification` returns the challenge as plain text |

Setup flow:

1. Create or edit a Hooksbase webhook with `providerSource.provider = "slack"`.
2. Store the Slack signing secret as `providerSource.config.signingSecret`.
3. Configure Slack to send requests to the Hooksbase ingest URL, or to a forwarder that adds the Hooksbase ingest bearer header.
4. Expect Slack `url_verification` to return text immediately and not create a delivery.
5. Use `provider.eventType` for values such as `app_mention`, `message.channels`, and `slash_command`.

Slack metadata on accepted deliveries includes the event source id, event type, team id, app id, and slash-command name when present.

## Resend

Use the Resend pack for Svix-signed JSON events such as `email.delivered`, `domain.created`, and `contact.created`.

| Field | Value | | --- | --- | | Pack id | `resend` | | Supported content type | `application/json` | | Required pack secret | `signingSecret` | | Required provider headers | `svix-id`, `svix-timestamp`, `svix-signature` | | Challenge behavior | None |

Setup flow:

1. Create or edit a Hooksbase webhook with `providerSource.provider = "resend"`.
2. Store the Resend signing secret as `providerSource.config.signingSecret`.
3. Configure Resend to send JSON events to the Hooksbase ingest URL, or to a forwarder that adds the Hooksbase ingest bearer header.
4. Use `provider.eventType` to route email, domain, and contact events.

Resend metadata on accepted deliveries includes the Svix message id, event type, object type, and nested data id when present.

## Routing fields

Every accepted provider delivery can be routed by:

- `provider.name`
- `provider.sourceId`
- `provider.eventType`
- `provider.verified`

Provider verification does not rewrite the payload into a vendor-neutral schema. Routing sees the original source payload plus the normalized provider metadata; payload transforms run after route selection and shape the outbound dispatch body.

## Common mistakes

- Sending provider traffic directly without the Hooksbase ingest bearer header.
- Letting a forwarder parse and reserialize the body before verification. Keep raw bytes intact.
- Using the wrong secret field name. GitHub uses `secret`; the other current packs use `signingSecret`.
- Expecting failed provider verification to appear in delivery history. Failed verification is rejected before persistence.
- Treating Slack URL verification as a delivery. It returns the challenge text instead.