Skip to main content

Webhook Endpoints (Sources)

A webhook endpoint is the entry point for incoming webhooks. Each endpoint has a unique slug that forms its URL: POST /hooks/:slug.

Adding a Source​

When you add a source, Dispatch generates:

  • Slug — a URL-safe identifier (e.g., my-github-webhooks)
  • Signing Secret — an HMAC secret for verifying request authenticity

Configuration Options​

FieldDescription
NameDisplay name for the endpoint
SlugURL path segment (auto-generated, can be customized)
Signing SecretSecret used to verify incoming request signatures
Event Type PathDot-notation path to extract event type from the payload body (e.g., action or event.type)
ProviderOptional: github, gitlab, bitbucket, slack, jira, linear, or stripe for provider-specific behavior
Is ActiveToggle to enable/disable the endpoint

Event Type Extraction​

Dispatch determines the event type from (in order of priority):

  1. X-GitHub-Event header (GitHub webhooks)
  2. X-Gitlab-Event header (GitLab webhooks)
  3. X-Event-Type header (custom header)
  4. Slack event type from payload structure (event.type in event_callback payloads)
  5. Linear event type from type field in the request body
  6. Stripe event type from type field in the request body (e.g., payment_intent.succeeded)
  7. The endpoint's configured event_type_path (dot-notation path into the JSON body)

The event type is stored with the event and can be used for filtering destinations by event type.

Signature Verification​

All incoming requests must be authenticated using one of these methods:

HMAC Signature (Default)​

Include an HMAC-SHA256 signature of the request body in one of these headers:

  • X-Hub-Signature-256 (GitHub-compatible)
  • X-Dispatch-Signature

Format: sha256=<hex-encoded-hmac>

# Generate signature
SIGNATURE=$(echo -n "$BODY" | openssl dgst -sha256 -hmac "$SIGNING_SECRET" | cut -d' ' -f2)

curl -X POST https://api.dispatch.tech/hooks/my-slug \
  -H "Content-Type: application/json" \
  -H "X-Dispatch-Signature: sha256=$SIGNATURE" \
  -d "$BODY"

Slack Signature​

For Slack endpoints (provider = slack), Dispatch verifies the X-Slack-Signature header using the format:

v0:{timestamp}:{body}

The timestamp must be within 5 minutes of the current time to prevent replay attacks.

GitLab Token​

For GitLab endpoints (provider = gitlab), Dispatch checks the X-Gitlab-Token header for a literal match against the endpoint's signing secret:

X-Gitlab-Token: your-signing-secret

Linear Signature​

For Linear endpoints (provider = linear), Dispatch verifies the Linear-Signature header, which contains an HMAC-SHA256 hex digest of the request body:

Linear-Signature: <hex-encoded-hmac>

Stripe Signature​

For Stripe endpoints (provider = stripe), set the endpoint's signing secret to your Stripe webhook signing secret (begins with whsec_). Dispatch verifies the Stripe-Signature header:

Stripe-Signature: t=...,v1=...

To get the signing secret, copy the Webhook signing secret from your Stripe Dashboard webhook endpoint configuration.

Jira / Confluence JWT​

For Jira endpoints (provider = jira), Dispatch verifies the Authorization: Bearer <JWT> header included automatically by Jira when sending webhooks. When connecting via OAuth, Dispatch manages this automatically.

API Key​

Include a project API key in the Authorization header:

Authorization: Bearer dsp_your-api-key

An endpoint can be linked to multiple destinations. Each link can have:

  • An optional message template for formatting
  • Routing rules for conditional template selection
  • A JSONata transform applied before formatting

See Destinations, Templates, and Transforms for details.

Regenerating the Signing Secret​

You can regenerate an endpoint's signing secret from the dashboard. This immediately invalidates the old secret — update your external service configuration before the next webhook is sent.

Deactivating an Endpoint​

Setting an endpoint to inactive causes all incoming requests to that slug to return 404 Not Found. Existing events and delivery history are preserved.