Sources API

Sources are endpoints that receive incoming webhooks.

Endpoints

Method	Path	Description
GET	/api/organizations/{orgId}/sources	List sources
POST	/api/organizations/{orgId}/sources	Create source
GET	/api/organizations/{orgId}/sources/{id}	Get source
PATCH	/api/organizations/{orgId}/sources/{id}	Update source
DELETE	/api/organizations/{orgId}/sources/{id}	Delete source

Source Object

{
  "id": "src_abc123",
  "name": "GitHub Webhooks",
  "slug": "github",
  "description": "Production GitHub webhooks",
  "webhookUrl": "https://api.webhookrelay.com/ingest/myorg/github",
  "verificationConfig": {
    "type": "github",
    "secret": "********"
  },
  "enabled": true,
  "eventsCount": 1523,
  "lastEventAt": "2024-01-15T10:30:00Z",
  "createdAt": "2024-01-01T00:00:00Z",
  "updatedAt": "2024-01-15T10:30:00Z"
}

List Sources

GET /api/organizations/{orgId}/sources

Query Parameters

Parameter	Type	Description
page	number	Page number (default: 1)
pageSize	number	Items per page (default: 20, max: 100)
enabled	boolean	Filter by enabled status
search	string	Search by name or slug

Example

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

Response

{
  "data": [
    {
      "id": "src_abc123",
      "name": "GitHub Webhooks",
      "slug": "github",
      "webhookUrl": "https://api.webhookrelay.com/ingest/myorg/github",
      "enabled": true,
      "eventsCount": 1523
    }
  ],
  "pagination": {
    "total": 5,
    "page": 1,
    "pageSize": 20
  }
}

Create Source

POST /api/organizations/{orgId}/sources

Request Body

Field	Type	Required	Description
name	string	Yes	Display name
slug	string	Yes	URL-safe identifier
description	string	No	Optional description
verificationConfig	object	No	Signature verification settings
enabled	boolean	No	Active status (default: true)

Verification Config Options

GitHub

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

Stripe

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

Slack

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

Generic HMAC

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

None

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

Example

curl -X POST https://api.webhookrelay.com/api/organizations/org_123/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": "my-secret-key"
    }
  }'

Response

{
  "id": "src_def456",
  "name": "GitHub Production",
  "slug": "github-prod",
  "description": "Production GitHub webhooks",
  "webhookUrl": "https://api.webhookrelay.com/ingest/myorg/github-prod",
  "verificationConfig": {
    "type": "github"
  },
  "enabled": true,
  "eventsCount": 0,
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-15T10:30:00Z"
}

Get Source

GET /api/organizations/{orgId}/sources/{id}

Example

curl https://api.webhookrelay.com/api/organizations/org_123/sources/src_abc123 \
  -H "Authorization: Bearer YOUR_TOKEN"

Response

{
  "id": "src_abc123",
  "name": "GitHub Webhooks",
  "slug": "github",
  "description": "Production GitHub webhooks",
  "webhookUrl": "https://api.webhookrelay.com/ingest/myorg/github",
  "verificationConfig": {
    "type": "github"
  },
  "enabled": true,
  "eventsCount": 1523,
  "lastEventAt": "2024-01-15T10:30:00Z",
  "createdAt": "2024-01-01T00:00:00Z",
  "updatedAt": "2024-01-15T10:30:00Z"
}

Update Source

PATCH /api/organizations/{orgId}/sources/{id}

Request Body

All fields are optional. Only provided fields are updated.

Field	Type	Description
name	string	Display name
description	string	Optional description
verificationConfig	object	Signature verification settings
enabled	boolean	Active status

WARNING

The slug cannot be changed after creation as it's part of the webhook URL.

Example

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

Response

{
  "id": "src_abc123",
  "name": "GitHub Production (Updated)",
  "slug": "github",
  "enabled": false,
  "updatedAt": "2024-01-15T11:00:00Z"
}

Delete Source

DELETE /api/organizations/{orgId}/sources/{id}

DANGER

Deleting a source also deletes all associated events and deliveries.

Example

curl -X DELETE https://api.webhookrelay.com/api/organizations/org_123/sources/src_abc123 \
  -H "Authorization: Bearer YOUR_TOKEN"

Response

204 No Content

Error Responses

400 Bad Request

Invalid input data:

{
  "error": "Bad Request",
  "message": "Slug must be lowercase alphanumeric with hyphens",
  "code": "INVALID_SLUG"
}

404 Not Found

Source not found:

{
  "error": "Not Found",
  "message": "Source with ID src_xyz not found",
  "code": "RESOURCE_NOT_FOUND"
}

409 Conflict

Duplicate slug:

{
  "error": "Conflict",
  "message": "A source with slug 'github' already exists",
  "code": "DUPLICATE_SLUG"
}