Configurar webhook

Cada instância tem uma URL de webhook para onde a ZapDev entrega os eventos do WhatsApp. Configure essa URL pela API, o mesmo que você faz no painel, e leia o segredo usado na assinatura.

O :instanceId é o Instance ID da instância dona do token. O token no header Authorization já identifica a instância, então o :instanceId da URL precisa ser o dela, veja Autenticação.

Obter a configuração

GEThttps://api.zapdev.com.br/v1/webhooks/:instanceId

200 OK com a configuração atual do webhook da instância.

Campo	Tipo	Descrição
instanceId	string	Instance ID da instância
url	string | null	URL de entrega dos eventos. null se nenhuma foi configurada.
secret	string	Segredo do HMAC. Use para validar o header X-ZapDev-Signature.
active	boolean	true quando há uma URL configurada

Resposta

cURL

curl https://api.zapdev.com.br/v1/webhooks/ins_abc123 \
  -H "Authorization: Bearer zd_live_..."

200 OK

{
  "data": {
    "instanceId": "ins_abc123",
    "url": "https://seuapp.com/webhooks/zapdev",
    "secret": "whsec_9f2a...",
    "active": true
  }
}

Dica

O secret é o mesmo valor usado para validar a assinatura dos eventos recebidos. Guarde-o com segurança e nunca o exponha no frontend, veja Validando a assinatura.

Atualizar a URL

PUThttps://api.zapdev.com.br/v1/webhooks/:instanceId

Envie a nova URL no corpo. Ela passa a valer para os próximos eventos, entregas já enfileiradas seguem para a URL anterior.

Campo	Tipo	Descrição
url (obrig.)	string	URL HTTPS pública que recebe os eventos (POST)

Requisição

cURL

curl -X PUT https://api.zapdev.com.br/v1/webhooks/ins_abc123 \
  -H "Authorization: Bearer zd_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://seuapp.com/webhooks/zapdev" }'

200 OK

{
  "data": {
    "instanceId": "ins_abc123",
    "url": "https://seuapp.com/webhooks/zapdev",
    "secret": "whsec_9f2a...",
    "active": true
  }
}

Erros

HTTP	error.code	Quando
401	invalid_token	token ausente ou inválido
404	instance_not_found	o :instanceId não é o da instância do token
400	invalid_request	url ausente ou sem protocolo (http/https)
429	rate_limit_exceeded	acima de 100 req/min na instância

Envelope completo em Erros.

Como funciona a entrega

Depois de configurada, cada evento é entregue com POST na sua URL, assinado com o secret no header X-ZapDev-Signature. Se ela não responder 2xx, a ZapDev reenvia com backoff (1s, 5s, 30s, 2min, 10min). Detalhes do payload, da assinatura e do retry em Webhooks.