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" }
}'const endpoint = await relay.endpoints.create({
url: "https://api.acme.com/webhooks",
events: ["invoice.*"],
metadata: { customer_id: "cus_77" },
});endpoint = relay.endpoints.create(
url="https://api.acme.com/webhooks",
events=["invoice.*"],
metadata={"customer_id": "cus_77"},
)Response
{
"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.