Create inbound endpoint

POST

/v1/inbound-endpoints

• Production

Create a new inbound webhook endpoint for receiving webhooks from external sources. The endpoint URL must be HTTPS and publicly accessible. A secret token and ingest URL are returned only in this response.

If signing_enabled=true, the initial delivery signing key is also created and its signing_secret is returned only in this response.

Important: The secret_token, ingest_url, and signing_secret are only returned once. Store them securely.

Authorizations

• BearerAuth

Request Body ^required

object

name

Friendly name for the inbound endpoint

string

<= 255 characters

Example

Stripe webhooks

description

Optional description

string

<= 500 characters

Example

Receives Stripe payment events

mode

Endpoint mode. forward delivers webhooks to the URL via HTTP. cli streams webhooks to a connected CLI tool (no HTTP delivery).

string

default: forward

Allowed values: forward cli pull

Example

forward

url

HTTPS URL of your endpoint that will receive forwarded webhooks. Required when mode is forward. Optional when mode is cli. Must be publicly accessible. Internal/private IP addresses are blocked.

string format: uri

>= 12 characters <= 2048 characters /^https:///

Example

https://myapp.com/webhooks/stripe

verify_static_token

Enable static token verification on incoming webhooks

boolean

token_header_name

Header name containing the static token (if verify_static_token is true)

string

Example

X-Webhook-Token

token_query_param

Query parameter name containing the static token (alternative to header)

string

Example

token

token_value

The static token value (will be hashed for storage)

string

Example

my-secret-token

verify_hmac

Enable HMAC signature verification on incoming webhooks

boolean

hmac_header_name

Header name containing the HMAC signature (if verify_hmac is true)

string

Example

X-Signature

hmac_secret

HMAC secret key (will be encrypted for storage)

string

Example

whsec_abc123

timestamp_header_name

Header name containing the request timestamp for replay protection

string

Example

X-Webhook-Timestamp

timestamp_ttl_seconds

Maximum age in seconds for timestamp validation

integer

>= 1

Example

300

verify_ip_allowlist

Enable IP allowlist verification on incoming webhooks

boolean

allowed_cidrs

CIDR blocks allowed to send webhooks (if verify_ip_allowlist is true)

Array<string>

Example

[
  "203.0.113.0/24",
  "198.51.100.0/24"
]

idempotency_header_names

Ordered list of header names to derive idempotency keys from incoming requests

Array<string>

Example

[
  "X-Idempotency-Key"
]

ingest_response_code

HTTP status code returned to senders on successful ingestion

integer

default: 202 >= 200 <= 299

Example

202

signing_enabled

Enable HMAC signing on forwarded deliveries (secret auto-generated)

boolean

ephemeral

If true, creates an ephemeral inbound endpoint for CI/test workflows. Ephemeral endpoints auto-expire after the TTL.

boolean

ttl_minutes

Time-to-live in minutes for ephemeral endpoints. Only used when ephemeral is true. After this duration, the endpoint is automatically deleted.

integer

default: 30 >= 1 <= 1440

Example

60

Examples

Basic inbound endpoint

{
  "url": "https://myapp.com/webhooks/stripe",
  "name": "Stripe webhooks"
}

Endpoint with HMAC verification

{
  "url": "https://myapp.com/webhooks/stripe",
  "name": "Stripe webhooks",
  "verify_hmac": true,
  "hmac_header_name": "Stripe-Signature",
  "hmac_secret": "whsec_abc123"
}

Endpoint with IP allowlist

{
  "url": "https://myapp.com/webhooks/partner",
  "name": "Partner webhooks",
  "verify_ip_allowlist": true,
  "allowed_cidrs": [
    "203.0.113.0/24",
    "198.51.100.0/24"
  ]
}

CLI-mode endpoint (for local development)

{
  "name": "Local dev webhooks",
  "mode": "cli"
}

Responses

201

Inbound endpoint created successfully

object

data

object

id

Unique inbound endpoint identifier (UUIDv7)

string format: uuid

Example

01935abc-def0-7123-4567-890abcdef012

name

Endpoint name

string

Example

Stripe webhooks

url

Forwarding URL (empty for cli-mode endpoints)

string format: uri

Example

https://myapp.com/webhooks/stripe

mode

Endpoint mode

string

Allowed values: forward cli pull

Example

forward

ingest_url

Shown only once! The full URL that external senders should POST webhooks to.

string format: uri

Example

https://receive.hookbridge.io/v1/webhooks/receive/01935abc-def0-7123-4567-890abcdef012/a1b2c3d4e5f6

secret_token

Shown only once! 32-character hex token embedded in the ingest URL.

string

Example

a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4

signing_key_id

Initial signing key ID when delivery signing is enabled

string

Example

sk_550e8400e29b41d4a716446655440001

signing_secret

Shown only once! Initial delivery signing secret when signing is enabled.

string

Example

whsec_newabcdefghijklmnopqrstuvwxyz12

key_hint

Last 4 chars of the signing key for identification

string

Example

wxyz

ephemeral

Whether this is an ephemeral (CI/test) endpoint

boolean

expires_at

When the ephemeral endpoint will auto-expire (only present for ephemeral endpoints)

string format: date-time

Example

2026-06-01T12:30:00Z

created_at

string format: date-time

Example

2025-12-06T12:00:00Z

meta

object

request_id

Unique identifier for this request (useful for support)

string

Example

req_xyz123

Example

{
  "data": {
    "id": "01935abc-def0-7123-4567-890abcdef012",
    "name": "Stripe webhooks",
    "url": "https://myapp.com/webhooks/stripe",
    "ingest_url": "https://receive.hookbridge.io/v1/webhooks/receive/01935abc-def0-7123-4567-890abcdef012/a1b2c3d4e5f6",
    "secret_token": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
    "signing_key_id": "sk_550e8400e29b41d4a716446655440001",
    "signing_secret": "whsec_newabcdefghijklmnopqrstuvwxyz12",
    "key_hint": "wxyz",
    "created_at": "2025-12-06T12:00:00Z"
  },
  "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

Duplicate URL 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": "DUPLICATE_URL",
    "message": "An inbound endpoint with this URL already exists in this project"
  },
  "meta": {
    "request_id": "req_xyz123"
  }
}