Subscribe to an event (integrations)
Registers an automation platform's URL for an event, the way Zapier REST hooks subscribe when a Zap turns on. bannx then POSTs `{ id, event, timestamp, spaceId, data }` to `targetUrl` each time the event happens in the key's space; for `render.completed`, `data` holds `templateId`, `format` and `url`. Bearer API key with the `webhook.manage` scope, whose user may manage webhooks in the space. `targetUrl` must be a public HTTPS URL. `templateId` is stored with the subscription so the platform can filter; delivery is not filtered.
Subscribe to an event (integrations)
Registers an automation platform's URL for an event, the way Zapier REST hooks subscribe when a Zap turns on. bannx then POSTs `{ id, event, timestamp, spaceId, data }` to `targetUrl` each time the event happens in the key's space; for `render.completed`, `data` holds `templateId`, `format` and `url`. Bearer API key with the `webhook.manage` scope, whose user may manage webhooks in the space. `targetUrl` must be a public HTTPS URL. `templateId` is stored with the subscription so the platform can filter; delivery is not filtered.
/api/v1/integrations/hooksRequest body
| Property | Type | Required | Description |
|---|---|---|---|
| targetUrl | string | Yes | Public HTTPS URL that receives the events. |
| event | render.completed | Yes | Event to subscribe to. |
| templateId | string | No | Optional template the subscriber cares about. |
| platform | string | No | Who is subscribing, shown in Settings → Developers. Default "integration". |
| secret | string | No | Optional, 16-200 characters. bannx then signs each delivery with `X-Webhook-Signature: sha256=<hex HMAC-SHA256 of the raw body>` so the receiver can verify it came from bannx. |
Responses
JSON { id, event, targetUrl } — keep `id` to unsubscribe.
targetUrl is not a public HTTPS URL, or the space has too many integration subscriptions (VALIDATION).
Missing or invalid API key, or the key lacks the webhook.manage scope (SCOPE_DENIED).
The key's user may not manage webhooks in the space (FORBIDDEN).
curl -X POST "https://bannx.com/api/v1/integrations/hooks" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-d '{"targetUrl":"string","event":null,"templateId":"string","platform":"string","secret":"string"}'// JSON { id, event, targetUrl } — keep `id` to unsubscribe.
{
"success": true,
"data": { ... }
}