Create inbound endpoint
const url = 'https://api.hookbridge.io/v1/inbound-endpoints';const options = { method: 'POST', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"url":"https://myapp.com/webhooks/stripe","name":"Stripe webhooks"}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url https://api.hookbridge.io/v1/inbound-endpoints \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "url": "https://myapp.com/webhooks/stripe", "name": "Stripe webhooks" }'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
Section titled “Authorizations”Request Bodyrequired
Section titled “Request Bodyrequired”object
Friendly name for the inbound endpoint
Optional description
Endpoint mode. forward delivers webhooks to the URL via HTTP.
cli streams webhooks to a connected CLI tool (no HTTP delivery).
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.
Enable static token verification on incoming webhooks
Header name containing the static token (if verify_static_token is true)
Query parameter name containing the static token (alternative to header)
The static token value (will be hashed for storage)
Enable HMAC signature verification on incoming webhooks
Header name containing the HMAC signature (if verify_hmac is true)
HMAC secret key (will be encrypted for storage)
Header name containing the request timestamp for replay protection
Maximum age in seconds for timestamp validation
Enable IP allowlist verification on incoming webhooks
CIDR blocks allowed to send webhooks (if verify_ip_allowlist is true)
Ordered list of header names to derive idempotency keys from incoming requests
HTTP status code returned to senders on successful ingestion
Enable HMAC signing on forwarded deliveries (secret auto-generated)
If true, creates an ephemeral inbound endpoint for CI/test workflows. Ephemeral endpoints auto-expire after the TTL.
Time-to-live in minutes for ephemeral endpoints. Only used when ephemeral is true. After this duration, the endpoint is automatically deleted.
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
Section titled “Responses”Inbound endpoint created successfully
object
object
Unique inbound endpoint identifier (UUIDv7)
Endpoint name
Forwarding URL (empty for cli-mode endpoints)
Endpoint mode
Shown only once! The full URL that external senders should POST webhooks to.
Shown only once! 32-character hex token embedded in the ingest URL.
Initial signing key ID when delivery signing is enabled
Shown only once! Initial delivery signing secret when signing is enabled.
Last 4 chars of the signing key for identification
Whether this is an ephemeral (CI/test) endpoint
When the ephemeral endpoint will auto-expire (only present for ephemeral endpoints)
object
Unique identifier for this request (useful for support)
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" }}Invalid request
object
object
Machine-readable error code
Human-readable error message
object
Unique identifier for this request (useful for support)
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" }}Unauthorized - Invalid or missing API key
object
object
Machine-readable error code
Human-readable error message
object
Unique identifier for this request (useful for support)
Example
{ "error": { "code": "UNAUTHORIZED", "message": "Invalid or missing API key" }, "meta": { "request_id": "req_xyz123" }}Duplicate URL conflict
object
object
Machine-readable error code
Human-readable error message
object
Unique identifier for this request (useful for support)
Example
{ "error": { "code": "DUPLICATE_URL", "message": "An inbound endpoint with this URL already exists in this project" }, "meta": { "request_id": "req_xyz123" }}Enter your credentials to populate code examples throughout the docs.