Skip to content
StraventaDocs
Now in Sandbox.

Create a webhook subscription

POST
/v1/admin/webhooks

Registers an endpoint for the caller's tenant and returns the row plus the plaintext hmac_secret — the only time it is ever readable. Store it on receipt; it is AES-GCM encrypted at rest and no endpoint returns it again. Supply your own hmac_secret to adopt an existing shared secret, or omit it and the server generates one.

url must be https:// and must resolve to a public address: plain http:// is rejected even on localhost, because these deliveries are HMAC-signed audit events and anyone on the wire could otherwise read a payload with its signature and forge later ones. Loopback, RFC1918, link-local and cloud-metadata addresses are refused as an SSRF guard. An empty event_filter subscribes to every event. Requires tenant.webhooks.write.

Authorization

bearerAuth
AuthorizationBearer <token>

JWT Bearer access token. Clock skew tolerance is ±60 seconds.

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://sandbox.505pay.link/v1/admin/webhooks" \  -H "Content-Type: application/json" \  -d '{    "url": "https://hooks.example.com/straventa",    "event_filter": [      "payment.succeeded"    ],    "active": true  }'
{
  "id": "018f6d0e-2222-7abc-8def-222222222222",
  "tenant_id": "018f6d0e-0000-7abc-8def-000000000000",
  "url": "https://hooks.example.com/straventa",
  "event_filter": [
    "payment.succeeded"
  ],
  "active": true,
  "consecutive_failures": 0,
  "created_at": "2026-09-05T02:15:00Z",
  "health": "healthy",
  "hmac_secret": "whsec_EXAMPLE_VALUE_NOT_A_REAL_SECRET"
}
{
  "error": "bad_request",
  "message": "malformed request",
  "request_id": "req_01abc128"
}
{
  "error": "unauthenticated",
  "message": "missing or invalid bearer token",
  "request_id": "req_01abc123"
}
{
  "error": "permission_denied",
  "message": "caller does not hold the required permission",
  "request_id": "req_01abc124"
}
{
  "error": "rate_limit_exceeded",
  "message": "Too many requests to /v1/admin (per-tenant policy)",
  "request_id": "req_01abc132"
}

Was this page helpful?