Webhooks
Avisos assinados do que acontece com seus agendamentos, com reenvio automático, log de entregas e exemplos para verificar a assinatura.
Atualizado:
Eventos
É possível assinar estes eventos:
| Evento | Quando |
|---|---|
booking.created | Uma pré-reserva ou agendamento foi criado |
booking.confirmed | Um agendamento foi confirmado |
booking.cancelled | Agendamento cancelado ou pré-reserva liberada |
booking.rescheduled | Mudou de horário (o payload traz o id antigo e o novo) |
booking.no_show | Marcado como falta |
booking.completed | Atendimento concluído |
booking.scheduled | Horário definido na mesma tarefa |
booking.unscheduled | Horário removido da tarefa |
booking.reassigned | Mudou o conjunto de corresponsáveis; data.booking.resource_ids contém todos os recursos posteriores e previous_resource_ids os anteriores. |
workitem.reopened | Uma tarefa foi reaberta |
workitem.stage_entered | A tarefa entrou em uma etapa |
workitem.stage_moved | A tarefa mudou de etapa |
workitem.tool_used | Uma ação ou ferramenta da etapa foi usada |
payment.paid | Provedor atualizou a cobrança para paga |
payment.recorded | Pagamento manual registrado |
payment.voided | Pagamento manual anulado |
message.received | Mensagem recebida persistida (IDs e tipo, sem texto) |
conversation.handoff | Conversa transferida para modo humano |
booking.reassigned: Só é emitido se havia pelo menos um recurso atribuído e o conjunto muda. Inclui remover a atribuição (novo conjunto vazio); exclui a atribuição inicial e repetir o mesmo recurso. A deduplicação usa a reserva e a sequência persistida de mudanças reais de recursos, independente da versão: A→B→A→B emite três eventos. Repetir o mesmo PATCH ou o conjunto atual não adiciona eventos nem incrementa a sequência.
Tipos inexistentes retornam 422 (invalid_webhook) com unsupported_events e a lista supported_events. webhook.ping é apenas um teste, não um tipo de assinatura. booking.cancelled não inclui a expiração automática de pré-reservas (booking.expired, evento interno).
Crie endpoints em Configurações → Webhooks no painel ou com POST /v1/webhook-endpoints (url e events). O segredo de assinatura (whsec_…) aparece uma única vez.
curl -X POST https://api.fiuit.com/v1/webhook-endpoints \
-H "Authorization: Bearer $WAGEND_KEY" \
-H "Content-Type: application/json" \
-d '{ "url": "https://example.com/wagend", "events": ["booking.confirmed", "booking.cancelled"] }'
Payload
O envelope mantém data.booking para agendamentos; cobranças usam data.payment (ID da cobrança), mensagens data.message (ID da mensagem), transferências data.conversation (ID da conversa) e eventos de tarefa (workitem.*) data.workitem (com etapa e status; o identificador é id para workitem.reopened e workitem_id para os demais eventos de tarefa). O texto da mensagem não é incluído.
{
"id": "evt_3f6c1d9e0b7a4c2f8e5d1a9b7c3e6f20",
"type": "booking.confirmed",
"created_at": "2026-10-14T15:21:07-03:00",
"workspace_id": "b3a6c8e2-5f1d-4c7a-9e0b-2d8f4a1c6e53",
"data": { "booking": { "id": "6d1f0c4a-7b2e-4a58-9c3d-0e5f8a2b1c47", "status": "confirmed", "start_at": "2026-10-15T12:45:00+00:00" } }
}
A entrega é pelo menos uma vez: use o id para ignorar duplicados.
Verificando a assinatura
Toda requisição traz o header:
Wagend-Signature: t=1791040867,v1=5c2b9f...e81
v1 é HMAC-SHA256(segredo, t + "." + corpo_bruto) em hexadecimal. Rejeite requisições com mais de 5 minutos e calcule a assinatura sobre o corpo bruto, sem serializar o JSON de novo.
import crypto from 'node:crypto'
export function verifyWagend(rawBody: string, header: string, secret: string) {
const parts = Object.fromEntries(header.split(',').map((p) => p.split('=') as [string, string]))
const age = Math.abs(Date.now() / 1000 - Number(parts.t))
if (!parts.t || !parts.v1 || age > 300) return false
const expected = crypto.createHmac('sha256', secret).update(`${parts.t}.${rawBody}`).digest('hex')
return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1))
}
import hashlib, hmac, time
def verify_wagend(raw_body: bytes, header: str, secret: str) -> bool:
parts = dict(p.split("=", 1) for p in header.split(","))
if abs(time.time() - int(parts.get("t", "0"))) > 300:
return False
signed = f"{parts['t']}.".encode() + raw_body
expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, parts.get("v1", ""))
Reenvios
Responda com qualquer 2xx em até 10 segundos. Caso contrário, tentamos de novo após 1 min, 5 min, 30 min, 2 h e 12 h. Cada tentativa aparece no log de entregas, onde você também pode reenviar manualmente.
Segurança e limites
- A URL deve ser
httpse resolver para um endereço público: rejeitamoslocalhost, redes privadas, link-local e endereços de metadados de nuvem (ao cadastrar e a cada entrega). Não seguimos redirecionamentos (um3xxconta como falha). - Cabeçalhos extras:
Wagend-Event(tipo) eWagend-Delivery(id da entrega). Cada tentativa é assinada com um timestamp novo. - Até 10 endpoints por workspace. Após 10 falhas consecutivas o endpoint é desativado (reative com
PATCH /v1/webhook-endpoints/{id}e{"active": true}). POST /v1/webhook-endpoints/{id}/pingenvia um evento de testewebhook.ping;POST /v1/webhook-endpoints/{id}/rotate-secretgera um novo segredo (mostrado uma única vez; o anterior deixa de valer na hora).- Com API key use o escopo
webhooks:manage. O log fica emGET /v1/webhook-endpoints/{id}/deliveriese o reenvio emPOST …/deliveries/{delivery_id}/resend.