Webhook Ingress

The ingress endpoint is the main entry point for receiving webhooks from external services.

POST /hooks/:slug

Receive and process a webhook event.

Path Parameters

Parameter	Type	Description
slug	string	The unique endpoint slug

Headers

Header	Required	Description
Content-Type	Yes	Must be application/json
X-Hub-Signature-256	Conditional	GitHub/Bitbucket HMAC-SHA256 signature (sha256= prefix)
X-Dispatch-Signature	Conditional	Custom HMAC-SHA256 signature
X-Slack-Signature	Conditional	Slack signature (with X-Slack-Request-Timestamp)
X-Gitlab-Token	Conditional	GitLab secret token
Linear-Signature	Conditional	Linear HMAC-SHA256 signature
Stripe-Signature	Conditional	Stripe webhook signature (t= + v1=)
Authorization	Conditional	Jira/Confluence JWT Bearer token, or Bearer dsp_<api-key>
X-GitHub-Event	No	GitHub event type (auto-detected)
X-Gitlab-Event	No	GitLab event type (auto-detected)
X-Event-Type	No	Custom event type header

At least one authentication header is required (signature or API key).

Limits

Limit	Value
Maximum payload size	10 MiB
Rate limit	100 requests/sec per IP

Request Body

Any valid JSON object.

{
  "action": "push",
  "repository": {
    "full_name": "owner/repo"
  },
  "sender": {
    "login": "username"
  }
}

Response

202 Accepted — Event received and queued for delivery.

{
  "event_id": "550e8400-e29b-41d4-a716-446655440000"
}

Error Responses

Status	Description
400 Bad Request	Invalid JSON body
401 Unauthorized	Invalid signature or API key
404 Not Found	Endpoint not found or inactive
409 Conflict	Duplicate event (idempotency key already used)
429 Too Many Requests	Organization event limit reached
500 Internal Server Error	Failed to store event

Processing Pipeline

1. Endpoint lookup — find active endpoint by slug
2. Authentication — verify signature or API key
3. Payload validation — ensure valid JSON
4. Slack challenge — if Slack URL verification, respond immediately
5. Event type extraction — from headers or payload path
6. Header collection — store all request headers
7. Usage check — verify org hasn't exceeded event limits
8. Event storage — persist the event
9. Filter evaluation — if blocked, mark as filtered and stop
10. Fan-out — create delivery jobs for all active linked destinations
11. Queue — enqueue jobs for async delivery

Slack URL Verification

When Slack sends a URL verification challenge, Dispatch responds immediately:

// Incoming
{
  "type": "url_verification",
  "challenge": "abc123"
}

// Response (200 OK)
{
  "challenge": "abc123"
}

This is handled before event storage, so no event is created for verification requests.

Response Headers

Header	Description
X-Request-ID	Unique request ID for tracing