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:

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 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

  • Name
    Public API
    Type
    project API key
    Description

    Use project-authenticated webhook routes to read the HTTP pack catalog, inspect template availability, and create a webhook with a providerSource and optional template.

  • Name
    Dashboard
    Type
    session auth
    Description

    The dashboard provides the same provider catalog and templated webhook creation flows as a UI, with the same Starter+ availability checks applied.

  • Name
    SDK / CLI
    Description

    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 reads the same catalog when rendering the templated webhook creation flow.

Inspect the HTTP pack catalog

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 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 for route-to-one rules and transforms when you want to reshape the outbound JSON after the provider check succeeds.

  • 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.

Was this page helpful?