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.webhookrelay.com/ingest/{orgSlug}/{sourceSlug}

When a webhook arrives at this URL, WebhookRelay:

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

Field	Description
name	Human-readable name for the source
slug	URL-safe identifier (lowercase, alphanumeric, hyphens)

Optional Fields

Field	Description
description	Optional description
verificationConfig	Signature verification settings
enabled	Whether the source is active (default: true)

Signature Verification

WebhookRelay 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"
  }
}

Headers Captured

WebhookRelay 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.webhookrelay.com/api/organizations/{orgId}/sources \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -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.webhookrelay.com/ingest/myorg/github-prod",
  "verificationConfig": {
    "type": "github"
  },
  "enabled": true,
  "createdAt": "2024-01-15T10:30:00Z"
}

Managing Sources

List Sources

curl https://api.webhookrelay.com/api/organizations/{orgId}/sources \
  -H "Authorization: Bearer YOUR_TOKEN"

Get Source Details

curl https://api.webhookrelay.com/api/organizations/{orgId}/sources/{sourceId} \
  -H "Authorization: Bearer YOUR_TOKEN"

Update Source

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

Delete Source

curl -X DELETE https://api.webhookrelay.com/api/organizations/{orgId}/sources/{sourceId} \
  -H "Authorization: Bearer YOUR_TOKEN"

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