Configuration - Zapfy Docs

Zapfy uses a subscription model: instead of a single global URL that receives everything, you register endpoints and each one subscribes to the set of events it wants.

Want everything in one place → 1 endpoint with all events.
Want them split (e.g. message status to one service, connection to another) → separate endpoints, each with its own filter.

Limit of 5 endpoints per instance. Each endpoint is a delivery target per event; the cap prevents accidental amplification.

From the dashboard

Open the instance → Webhooks & config tab:

Add webhook.
Enter the Destination URL (HTTPS).
Check the Events that endpoint should receive.
Save. Use the Enabled toggle to pause delivery without deleting the endpoint.

From the API

The webhook endpoints use the account token (zpfy_acct_…). Generate it in the dashboard under API & Tokens → Account token → generate new. It is shown only once, and generating a new one revokes the previous token immediately — see Authentication.

string

required

HTTPS destination URL. Maximum of 2048 characters.

string[]

required

Subscribed events, at least one: MESSAGE.RECEIVED, MESSAGE.SENT, MESSAGE.STATUS_UPDATED, CONNECTION.UPDATED, QRCODE.UPDATED. What each one carries is in Events.

boolean

default:"true"

Whether the endpoint receives deliveries.

Create

curl -X POST https://api.zapfy.io/v1/instances/{instanceId}/webhooks \
  -H "Authorization: Bearer zpfy_acct_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/webhooks",
    "events": ["MESSAGE.RECEIVED", "MESSAGE.STATUS_UPDATED"]
  }'

{
  "data": {
    "id": "01J9Z...",
    "url": "https://your-app.com/webhooks",
    "events": ["MESSAGE.RECEIVED", "MESSAGE.STATUS_UPDATED"],
    "enabled": true,
    "secret": "whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw...",
    "createdAt": "2026-09-28T12:00:00.000Z"
  }
}

The secret is used to verify the signature of each delivery. It is only shown in this response — store it. A new or updated webhook starts receiving events within about 10 seconds.

List, update and delete

# list
curl https://api.zapfy.io/v1/instances/{instanceId}/webhooks \
  -H "Authorization: Bearer zpfy_acct_xxxxxxxxxxxx"

# update (partial)
curl -X PATCH https://api.zapfy.io/v1/instances/{instanceId}/webhooks/{webhookId} \
  -H "Authorization: Bearer zpfy_acct_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "enabled": false }'

# delete
curl -X DELETE https://api.zapfy.io/v1/instances/{instanceId}/webhooks/{webhookId} \
  -H "Authorization: Bearer zpfy_acct_xxxxxxxxxxxx"

Delivery

When the event happens, Zapfy sends a POST with a JSON body (envelope) to each endpoint subscribed to it. Every delivery is signed (webhook-id, webhook-timestamp and webhook-signature headers, Standard Webhooks format) — see Security.

Reply 2xx within 10 seconds. Anything else counts as a failure: another status code, a timeout, a connection error. Redirects are not followed — a 3xx is a failure too.
Failures are retried up to 6 attempts in total, about 5 minutes apart: the last attempt happens roughly 25 minutes after the first. After that, the event is no longer delivered to that endpoint.
Each endpoint is retried on its own. If one endpoint fails, the others that already received the event don’t receive it again.
At-least-once: the same event can arrive more than once, always with the same id.
No ordering guarantee: events can arrive in a different order from the one in which they happened.

How to deal with duplicates and ordering is in Handling events.

​From the dashboard

​From the API

​Create

​List, update and delete

​Delivery

From the dashboard

From the API

Create

List, update and delete

Delivery