# Providers And Templates

Provider-aware inbound is the fastest way to bootstrap a webhook that accepts a known third-party source, verifies its signature, and stamps normalized provider metadata onto every delivery. Use this layer when you want more than a generic raw HTTP receiver.

## Provider-aware inbound

The current HTTP pack catalog covers:

- [Stripe](/docs/provider-setup.md#stripe)
- [GitHub](/docs/provider-setup.md#github)
- [Clerk](/docs/provider-setup.md#clerk)
- [Slack](/docs/provider-setup.md#slack)
- [Resend](/docs/provider-setup.md#resend)

Provider-aware webhooks add three things on top of a generic ingest endpoint:

- signature verification using the provider's signing secret shape — requests that fail verification are rejected before a delivery is persisted, so a non-verified request never appears in your delivery history
- normalized delivery metadata such as `provider`, `providerSourceId`, `providerEventType`, and `providerVerified`, stamped onto every delivery
- template bootstrap for common forwarding recipes and routing presets

This is a Starter+ workflow. If you only need to accept unsigned generic JSON, stay on the normal [ingest](/docs/ingest.md) surface — you get the same URL and delivery model without the provider verification step.

Provider verification runs after Hooksbase ingest authentication. The producer still has to send `Authorization: Bearer whsec_...` to the normal ingest URL; if a provider dashboard cannot attach that header, put a small pass-through forwarder in front of Hooksbase that preserves the raw body and signature headers while adding the Hooksbase bearer secret.

## Auth model

- **Public API** `project API key`: Use project-authenticated webhook routes to read the HTTP pack catalog, inspect template availability, and create a webhook with a `providerSource` and optional `template`.
- **Dashboard** `session auth`: The [dashboard](/docs/dashboard.md) provides the same provider catalog and templated webhook creation flows as a UI, with the same Starter+ availability checks applied.
- **SDK / CLI**: HTTP packs are raw-HTTP only today, but the template catalog is wrapped by `client.templates.list()` in the SDK and `hooksbase templates list` in the CLI.

## HTTP packs and templates

HTTP packs describe what a provider needs:

- supported content types
- secret field shape
- challenge behavior when the provider requires a synchronous response
- example headers and setup notes
- template recipes that can bootstrap routing and destination defaults

The Public API catalog lives at `GET /v1/webhooks/http-packs` and `GET /v1/webhooks/templates`. The [dashboard](/docs/dashboard.md) reads the same catalog when rendering the templated webhook creation flow.

**Inspect the HTTP pack catalog**

```bash
curl https://api.hooksbase.com/v1/webhooks/http-packs \
  -H "Authorization: Bearer swk_..."
```

When you create a templated webhook:

- `providerSource.provider` must match the template provider
- the chosen default destination type must match the template recipe
- Hooksbase can pre-seed route-to-one rules and keep the transform empty or preconfigured depending on the recipe

## Verification and challenge flows

Verification runs before the delivery is accepted. If signature checks fail, the request is rejected instead of creating a delivery row.

Provider-specific details that matter:

- Stripe uses the Stripe signature header and verified raw JSON body
- GitHub uses `x-hub-signature-256` plus the delivery id/event headers
- Clerk and Resend use Svix-style signing
- Slack verifies the signed raw payload and can respond to `url_verification` with the challenge text instead of accepting a delivery

Use the [provider setup guide](/docs/provider-setup.md) for the exact pack id, secret field, required headers, challenge behavior, and routing metadata for each provider.

Provider-aware inbound still routes and transforms like any other webhook after verification. Use [routing](/docs/routing.md) for route-to-one rules and [transforms](/docs/transforms.md) when you want to reshape the outbound JSON after the provider check succeeds.

## Related routes

- `GET /v1/webhooks/http-packs`
- `GET /v1/webhooks/templates`
- `POST /v1/webhooks`

## Common mistakes

- Treating HTTP packs as a separate ingest endpoint. They configure a normal webhook.
- Choosing a template whose destination type does not match the default destination.
- Assuming provider verification rewrites the payload into a vendor-neutral schema.
- Forgetting that Slack `url_verification` can return a synchronous text challenge instead of creating a delivery.