Send a webhook

POST

/v1/webhooks/send

curl --request POST \
  --url https://send.hookbridge.io/v1/webhooks/send \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "endpoint_id": "ep_550e8400e29b41d4a716446655440000", "payload": { "event": "order.created", "order_id": "ord_12345", "amount": 99.99 } }'

• Send service (separate host from the main API)

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

Media typeapplication/json

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}$/

payload

required

JSON payload to send (max 1 MB)

object

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

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_-]+$/

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

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

Media typeapplication/json

object

data

object

message_id

Unique identifier for the queued message (UUIDv7)

string format: uuid

status

Initial message status

string

Allowed values: queued

meta

object

request_id

Unique identifier for this request (useful for support)

string

Example

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

400

Invalid request

Media typeapplication/json

object

error

object

code

Machine-readable error code

string

message

Human-readable error message

string

meta

object

request_id

Unique identifier for this request (useful for support)

string

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

Media typeapplication/json

object

error

object

code

Machine-readable error code

string

message

Human-readable error message

string

meta

object

request_id

Unique identifier for this request (useful for support)

string

Example

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

409

Idempotency key conflict

Media typeapplication/json

object

error

object

code

Machine-readable error code

string

message

Human-readable error message

string

meta

object

request_id

Unique identifier for this request (useful for support)

string

Example

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

413

Payload too large

Media typeapplication/json

object

error

object

code

Machine-readable error code

string

message

Human-readable error message

string

meta

object

request_id

Unique identifier for this request (useful for support)

string

Example

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

429

Rate limit exceeded

Media typeapplication/json

object

error

object

code

Machine-readable error code

string

message

Human-readable error message

string

meta

object

request_id

Unique identifier for this request (useful for support)

string

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