Configuração - Zapfy Docs

A Zapfy usa um modelo de subscription: em vez de uma única URL global que recebe tudo, você cadastra endpoints e cada um assina o conjunto de eventos que quer.

Quem quer tudo num lugar só → 1 endpoint com todos os eventos.
Quem quer separar (ex.: status de mensagem num serviço, conexão em outro) → endpoints distintos, cada um com o seu filtro.

Limite de 5 endpoints por instância. Cada endpoint é um alvo de entrega por evento; o teto evita amplificação acidental.

Pelo painel

Abra a instância → aba Webhooks & config:

Adicionar webhook.
Informe a URL de destino (HTTPS).
Marque os Eventos que esse endpoint deve receber.
Salvar. Use o toggle Ativo para pausar a entrega sem apagar o endpoint.

Pela API

Os endpoints de webhook usam o token de conta (zpfy_acct_…). Gere-o no painel em API & Tokens → Token da conta → gerar novo. Ele aparece uma única vez, e gerar um novo revoga o anterior na hora — veja Autenticação.

string

obrigatório

URL HTTPS de destino. Máximo de 2048 caracteres.

string[]

obrigatório

Eventos assinados, ao menos um: MESSAGE.RECEIVED, MESSAGE.SENT, MESSAGE.STATUS_UPDATED, CONNECTION.UPDATED, QRCODE.UPDATED. O que cada um traz está em Eventos.

boolean

padrão:"true"

Se o endpoint recebe entregas.

Criar

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://seu-app.com/webhooks",
    "events": ["MESSAGE.RECEIVED", "MESSAGE.STATUS_UPDATED"]
  }'

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

O secret serve para verificar a assinatura de cada entrega. Ele só aparece nesta resposta — guarde-o. Um webhook novo ou alterado passa a receber eventos em até cerca de 10 segundos.

Listar, atualizar e remover

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

# atualizar (parcial)
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 }'

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

Entrega

Quando o evento acontece, a Zapfy faz um POST com corpo JSON (envelope) em cada endpoint que o assina. Toda entrega é assinada (headers webhook-id, webhook-timestamp e webhook-signature, padrão Standard Webhooks) — veja Segurança.

Responda 2xx em até 10 segundos. Qualquer outra coisa conta como falha: outro status, timeout, erro de conexão. Redirecionamento não é seguido — um 3xx também é falha.
Falhas são reentregues até 6 tentativas no total, com cerca de 5 minutos entre elas: a última acontece por volta de 25 minutos depois da primeira. Depois disso, o evento deixa de ser entregue àquele endpoint.
Cada endpoint é reentregue por conta própria. Se um endpoint falha, os outros que já receberam o evento não o recebem de novo.
At-least-once: o mesmo evento pode chegar mais de uma vez, sempre com o mesmo id.
Sem garantia de ordem: os eventos podem chegar numa ordem diferente daquela em que aconteceram.

Como lidar com duplicatas e ordem está em Tratando eventos.

​Pelo painel

​Pela API

​Criar

​Listar, atualizar e remover

​Entrega

Pelo painel

Pela API

Criar

Listar, atualizar e remover

Entrega