Skip to content
RelayDocumentation

API ReferenceEndpoints

Create an endpoint

Register a URL that receives events, and get its signing secret.

POST/v1/endpoints

Body parameters

urlstringrequired
The URL that receives events. Must use HTTPS in live mode.
eventsstring[]default: ["*"]
Event types to subscribe to. Wildcards work: invoice.*.
descriptionstring
A label shown in the dashboard and the portal.
filterstring
Only deliver events whose payload matches. See Endpoints.
rate_limitinteger
Maximum deliveries per second to this endpoint.
headersobject
Extra headers sent with every delivery, e.g. {"X-Tenant": "acme"}.
metadataobject
Up to 20 key-value pairs for your own use, such as your customer ID.

Request

curl https://api.relay.dev/v1/endpoints \
  -H "Authorization: Bearer $RELAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://api.acme.com/webhooks",
    "events": ["invoice.*"],
    "metadata": { "customer_id": "cus_77" }
  }'

Response

201 Created
{
  "id": "ep_2kq8XcV1",
  "object": "endpoint",
  "url": "https://api.acme.com/webhooks",
  "events": ["invoice.*"],
  "status": "enabled",
  "secret": "whsec_C2FVsBQIhrscChlQIMV",
  "metadata": { "customer_id": "cus_77" },
  "created_at": "2026-10-14T09:12:40Z"
}

The full secret is only returned when the endpoint is created. Show it to your customer once, or store it encrypted.