Skip to content
HookBridge Docs

Create inbound endpoint

POST
/v1/inbound-endpoints

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.

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

Authorizations

Section titled “Authorizations ”

Request Body required

Section titled “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
url
required

HTTPS URL of your endpoint that will receive forwarded webhooks. 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
Examples

Basic inbound endpoint

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

Responses

Section titled “ Responses ”

201

Section titled “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

string format: uri
Example
https://myapp.com/webhooks/stripe
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
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",
    "created_at": "2025-12-06T12:00:00Z"
  },
  "meta": {
    "request_id": "req_xyz123"
  }
}

400

Section titled “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"
  }
}

401

Section titled “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

Section titled “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"
  }
}
Personalize Examples

Enter your credentials to populate code examples throughout the docs.