Sources

Sources are endpoints that receive incoming webhooks from external providers.

Overview

Each source has a unique URL where webhook providers send their payloads:

https://api.hookbase.app/ingest/{orgSlug}/{sourceSlug}

When a webhook arrives at this URL, Hookbase:

1. Validates the request (signature verification if configured)
2. Stores the event payload
3. Queues delivery to all destinations via connected routes

Creating a Source

Required Fields

Optional Fields

Signature Verification

Hookbase supports signature verification for popular providers to ensure webhooks are authentic.

GitHub

{
  "verificationConfig": {
    "type": "github",
    "secret": "your-github-webhook-secret"
  }
}

GitHub sends a X-Hub-Signature-256 header with an HMAC-SHA256 signature.

Stripe

{
  "verificationConfig": {
    "type": "stripe",
    "secret": "whsec_..."
  }
}

Stripe sends a Stripe-Signature header with timestamp and signature.

Slack

{
  "verificationConfig": {
    "type": "slack",
    "secret": "your-signing-secret"
  }
}

Slack sends X-Slack-Signature and X-Slack-Request-Timestamp headers.

HMAC (Generic)

For providers not specifically supported, use generic HMAC verification:

{
  "verificationConfig": {
    "type": "hmac",
    "secret": "your-secret",
    "algorithm": "sha256",
    "header": "X-Signature",
    "encoding": "hex"
  }
}

Options:

• algorithm: sha1, sha256, sha512
• encoding: hex, base64
• header: The header containing the signature
• prefix: Optional prefix to strip (e.g., sha256=)

None

To disable verification:

{
  "verificationConfig": {
    "type": "none"
  }
}

Accepted HTTP Methods

By default a source's ingest endpoint accepts any HTTP method — POST, GET, PUT, PATCH, DELETE and HEAD all work. This lets you receive webhooks from systems that don't use POST, such as legacy services that ping a URL with GET and a query string.

To restrict a source, set allowedMethods:

{
  "allowedMethods": ["POST", "PUT"]
}

Any other method is then rejected with 405 Method Not Allowed and an Allow header listing what the source accepts:

HTTP/1.1 405 Method Not Allowed
Allow: POST, PUT
 
{
  "error": "Method Not Allowed",
  "code": "METHOD_NOT_ALLOWED",
  "message": "This source accepts POST, PUT. Received GET."
}

Rejected requests are not counted against your monthly event quota.

To go back to accepting every method, send an empty array — "allowedMethods": [] — or clear all the toggles in the dashboard. An empty list and no list mean the same thing.

Bodiless Methods and the Query String

GET, HEAD and DELETE carry no request body, so Hookbase builds the event payload from the query string instead:

curl "https://api.hookbase.app/ingest/acme/legacy-pings?status=ok&id=42"

produces the payload:

{ "status": "ok", "id": "42" }

A repeated key collects into an array — ?tag=a&tag=b becomes {"tag": ["a", "b"]} — and a request with no query string produces {}. Values are URL-decoded. Because this is a normal payload, filters, transforms and schema validation all work against it as usual.

The stored event records the verb it arrived with under the :method header, so you can tell GET and POST events apart in the dashboard and in filters.

Headers Captured

Hookbase captures and stores these headers from incoming webhooks:

• Content-Type
• X-GitHub-Event
• X-GitHub-Delivery
• Stripe-Signature
• X-Shopify-Topic
• X-Slack-Signature
• All custom X-* headers

Example: Creating a Source

curl -X POST https://api.hookbase.app/api/sources \
  -H "Authorization: Bearer whr_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "GitHub Production",
    "slug": "github-prod",
    "description": "Production GitHub webhooks",
    "verificationConfig": {
      "type": "github",
      "secret": "super-secret-key"
    }
  }'

Response:

{
  "id": "src_abc123",
  "name": "GitHub Production",
  "slug": "github-prod",
  "webhookUrl": "https://api.hookbase.app/ingest/myorg/github-prod",
  "verificationConfig": {
    "type": "github"
  },
  "enabled": true,
  "createdAt": "2024-01-15T10:30:00Z"
}

Managing Sources

List Sources

curl https://api.hookbase.app/api/sources \
  -H "Authorization: Bearer whr_your_api_key"

Get Source Details

curl https://api.hookbase.app/api/sources/{sourceId} \
  -H "Authorization: Bearer whr_your_api_key"

Update Source

curl -X PATCH https://api.hookbase.app/api/sources/{sourceId} \
  -H "Authorization: Bearer whr_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "GitHub Production (Updated)",
    "enabled": false
  }'

Delete Source

curl -X DELETE https://api.hookbase.app/api/sources/{sourceId} \
  -H "Authorization: Bearer whr_your_api_key"

Best Practices

1. Use descriptive slugs: Choose slugs that indicate the provider and environment (e.g., github-prod, stripe-test)

2. Always enable verification: When available, use signature verification to prevent unauthorized webhook submissions

3. Keep secrets secure: Store webhook secrets in environment variables, not in code

4. Use separate sources for environments: Create different sources for production, staging, and development

5. Monitor source health: Check the dashboard regularly for failed signature verifications

See Also

• Sources API — Full API reference
• Quick Start — Create your first source
• Integrations — Provider-specific setup guides
• IP Filtering — Restrict source IPs