Webhooks de saída — API Zyron Connect Suite

Module

Outbound webhooks

Configure where Connect delivers your connection's events. Deliveries carry an HMAC signature (x-zyron-signature) with backoff retries and dead-letter; structured events whatsapp.message.received|sent|delivered|read|failed and whatsapp.connection.updated.

GET/webhooks/webhooks PUT/webhooks/webhooks DELETE/webhooks/webhooks GET/webhooks/deliveries/webhooks/deliveries

GET/webhooksScope: readOfficial + Basic

List webhook configurations.

One configuration per connection. The secret is returned to the key owner — it validates the x-zyron-signature header. structured_events lists the v2 catalog.

Path parameters

No additional parameters.

Query parameters

Field	Type	Description
`connection_id`optional	uuid	Filters by connection.

Body fields

This endpoint does not receive a JSON body.

Ready examples

curl -X GET "https://connect.zyronstack.com/api/v1/webhooks?connection_id=<CONNECTION_ID>" \
  -H "Authorization: Bearer SUA_CHAVE_API"

Responses

200	Configurations returned.

Response example

{
  "data": [
    {
      "id": "5f0d5a44-1187-4f1e-a2b0-1d40c07b0e10",
      "connection_id": "<CONNECTION_ID>",
      "url": "https://seu-n8n.com/webhook/zyron",
      "events": ["whatsapp.message.received", "whatsapp.message.failed"],
      "secret": "zwh_9f2c...",
      "active": true
    }
  ],
  "structured_events": [
    "whatsapp.message.received",
    "whatsapp.message.sent",
    "whatsapp.message.delivered",
    "whatsapp.message.read",
    "whatsapp.message.failed",
    "whatsapp.connection.updated"
  ]
}

PUT/webhooksScope: writeOfficial + Basic

Create or update a connection's webhook.

Empty events subscribes to everything. Accepts v2 structured events plus native provider names (compatibility). Without a secret, Connect keeps the current one or generates a new zwh_.

Path parameters

No additional parameters.

Query parameters

No additional parameters.

Body fields

Field	Type	Description
`connection_id`required	uuid	Connection that owns the webhook.
`url`required	URL	http(s) endpoint receiving the events.
`events`optional	string[]	Subscribed events. Empty = all.
`secret`optional	string	HMAC secret. Optional; generated when absent.
`active`optional	boolean	Defaults to true. false pauses deliveries.

Ready examples

curl -X PUT "https://connect.zyronstack.com/api/v1/webhooks" \
  -H "Authorization: Bearer SUA_CHAVE_API" \
  -H "content-type: application/json" \
  -d '{
  "connection_id": "<CONNECTION_ID>",
  "url": "https://seu-n8n.com/webhook/zyron",
  "events": ["whatsapp.message.received", "whatsapp.message.failed"]
}'

Responses

201	Webhook created.
200	Webhook updated.
422	Invalid URL or unsupported event.

DELETE/webhooksScope: writeOfficial + Basic

Deactivate a connection's webhook.

Pauses deliveries while keeping the configuration and history. Reactivate with PUT { active: true }.

Path parameters

No additional parameters.

Query parameters

Field	Type	Description
`connection_id`required	uuid	Webhook's connection.

Body fields

This endpoint does not receive a JSON body.

Ready examples

curl -X DELETE "https://connect.zyronstack.com/api/v1/webhooks?connection_id=<CONNECTION_ID>" \
  -H "Authorization: Bearer SUA_CHAVE_API"

Responses

200	Webhook deactivated.
404	No webhook configured.

GET/webhooks/deliveriesScope: readOfficial + Basic

Webhook delivery history.

Each delivery shows event, status (pending, delivered, failed, dead), attempts, last HTTP status and error. Debug your endpoint without opening the panel.

Path parameters

No additional parameters.

Query parameters

Field	Type	Description
`connection_id`optional	uuid	Filters by connection.
`status`optional	pending \| delivered \| failed \| dead	Filters by delivery state.
`event`optional	string	Filters by delivered event name.
`limit`optional	number	Records per page. Default 50; maximum 200 on most list endpoints.
`offset`optional	number	Initial page index. Use pagination.next_offset to fetch the next page.

Body fields

This endpoint does not receive a JSON body.

Ready examples

curl -X GET "https://connect.zyronstack.com/api/v1/webhooks/deliveries?connection_id=<CONNECTION_ID>&status=failed" \
  -H "Authorization: Bearer SUA_CHAVE_API"

Responses

200	Deliveries returned.

Response example

{
  "data": [
    {
      "id": "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
      "connection_id": "<CONNECTION_ID>",
      "event": "whatsapp.message.received",
      "status": "delivered",
      "attempts": 1,
      "last_status": 200,
      "last_error": null,
      "target_url": "https://seu-n8n.com/webhook/zyron",
      "delivered_at": "2026-07-14T13:28:29.120Z",
      "created_at": "2026-07-14T13:28:27.898Z"
    }
  ],
  "pagination": { "limit": 50, "offset": 0, "total": 1, "next_offset": null }
}