Send a webhook

POST

/v1/webhooks/send

• Production

Enqueue a webhook for delivery. The webhook will be stored durably and delivered with automatic retries on failure. Returns immediately with a message ID for tracking.

Retry Behavior:

• Fast retries (for 429 responses): 30s, 60s, 120s, 240s, 300s
• Slow retries (for other errors): 30m, 2h, 6h, 12h, 24h, 48h, 72h, 96h
• Maximum 8 total attempts before moving to DLQ

Authorizations

• BearerAuth

Request Body ^required

object

endpoint_id

required

ID of the endpoint to deliver to. Endpoints must be created first via POST /v1/endpoints.

string

/^ep_[a-f0-9]{32}$/

Example

ep_550e8400e29b41d4a716446655440000

payload

required

JSON payload to send (max 1 MB)

object

Example

{
  "event": "order.created",
  "order_id": "ord_12345",
  "amount": 99.99
}

headers

Optional custom headers to include in the webhook request. Maximum 50 headers, 8KB total size. Some headers are forbidden (Host, Authorization, etc).

object

key

additional properties

string

Example

{
  "X-Tenant-Id": "tenant_abc",
  "X-Event-Type": "order.created"
}

idempotency_key

Optional idempotency key to prevent duplicate sends. If the same key is used with the same payload, the original message ID is returned. If the same key is used with a different payload, a 409 error is returned.

string

<= 255 characters /^[a-zA-Z0-9_-]+$/

Example

order-12345-created-v1

retention_hours

Optional override for payload retention period in hours. 0 means immediate delete after delivery. If not specified, the default retention for your plan is used. Maximum value depends on your subscription plan.

integer

Example

72

Examples

Basic webhook

{
  "endpoint_id": "ep_550e8400e29b41d4a716446655440000",
  "payload": {
    "event": "order.created",
    "order_id": "ord_12345",
    "amount": 99.99
  }
}

Webhook with custom headers

{
  "endpoint_id": "ep_550e8400e29b41d4a716446655440000",
  "payload": {
    "event": "order.created",
    "order_id": "ord_12345"
  },
  "headers": {
    "X-Tenant-Id": "tenant_abc",
    "X-Event-Type": "order.created"
  }
}

Webhook with idempotency key

{
  "endpoint_id": "ep_550e8400e29b41d4a716446655440000",
  "payload": {
    "event": "order.created",
    "order_id": "ord_12345"
  },
  "idempotency_key": "order-12345-created-v1"
}

Responses

200

Webhook successfully enqueued

object

data

object

message_id

Unique identifier for the queued message (UUIDv7)

string format: uuid

Example

01935abc-def0-7123-4567-890abcdef012

status

Initial message status

string

Allowed values: queued

Example

queued

meta

object

request_id

Unique identifier for this request (useful for support)

string

Example

req_xyz123

Example

{
  "data": {
    "message_id": "01935abc-def0-7123-4567-890abcdef012",
    "status": "queued"
  },
  "meta": {
    "request_id": "req_xyz123"
  }
}

400

Invalid request

object

error

object

code

Machine-readable error code

string

Example

INVALID_REQUEST

message

Human-readable error message

string

Example

endpoint must be a valid HTTPS URL

meta

object

request_id

Unique identifier for this request (useful for support)

string

Example

req_xyz123

Examples

Endpoint not found

{
  "error": {
    "code": "ENDPOINT_NOT_FOUND",
    "message": "endpoint not found"
  },
  "meta": {
    "request_id": "req_xyz123"
  }
}

Invalid endpoint ID format

{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "endpoint_id must be in format ep_xxx"
  },
  "meta": {
    "request_id": "req_xyz123"
  }
}

Invalid payload

{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "payload must be valid JSON"
  },
  "meta": {
    "request_id": "req_xyz123"
  }
}

Invalid headers

{
  "error": {
    "code": "INVALID_HEADERS",
    "message": "header 'Host' is forbidden and cannot be overridden"
  },
  "meta": {
    "request_id": "req_xyz123"
  }
}

401

Unauthorized - Invalid or missing API key

object

error

object

code

Machine-readable error code

string

Example

INVALID_REQUEST

message

Human-readable error message

string

Example

endpoint must be a valid HTTPS URL

meta

object

request_id

Unique identifier for this request (useful for support)

string

Example

req_xyz123

Example

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing API key"
  },
  "meta": {
    "request_id": "req_xyz123"
  }
}

409

Idempotency key conflict

object

error

object

code

Machine-readable error code

string

Example

INVALID_REQUEST

message

Human-readable error message

string

Example

endpoint must be a valid HTTPS URL

meta

object

request_id

Unique identifier for this request (useful for support)

string

Example

req_xyz123

Example

{
  "error": {
    "code": "IDEMPOTENCY_MISMATCH",
    "message": "Idempotency key already used with different payload"
  },
  "meta": {
    "request_id": "req_xyz123"
  }
}

413

Payload too large

object

error

object

code

Machine-readable error code

string

Example

INVALID_REQUEST

message

Human-readable error message

string

Example

endpoint must be a valid HTTPS URL

meta

object

request_id

Unique identifier for this request (useful for support)

string

Example

req_xyz123

Example

{
  "error": {
    "code": "PAYLOAD_TOO_LARGE",
    "message": "Payload exceeds maximum size of 1 MB"
  },
  "meta": {
    "request_id": "req_xyz123"
  }
}

429

Rate limit exceeded

object

error

object

code

Machine-readable error code

string

Example

INVALID_REQUEST

message

Human-readable error message

string

Example

endpoint must be a valid HTTPS URL

meta

object

request_id

Unique identifier for this request (useful for support)

string

Example

req_xyz123

Example

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded. Please try again later."
  },
  "meta": {
    "request_id": "req_xyz123"
  }
}

Headers

Retry-After

integer

Number of seconds to wait before retrying

Example

60