Webhooks

Os webhooks recebem eventos em tempo real através de HTTP POST para um URL configurado por si. Os mesmos eventos estão também disponíveis através de SSE. Os webhooks são configurados por organização - cada organização tem os seus próprios webhooks.

GestãoCopiar a ligação para esta secção

Consulte a especificação OpenAPI para os esquemas completos de pedido e resposta.

Criar um webhookCopiar a ligação para esta secção

POST /api/orgs/org_abc123/webhooks
Content-Type: application/json
x-api-key: tkn_xxx

{
  "url": "https://jouw-server.com/webhooks/tillor",
  "subscribedEventKeys": ["invoice:created", "invoice:paid", "customer:updated"],
  "enabled": true
}

• url - Endpoint HTTPS que aceita pedidos POST
• subscribedEventKeys - Array de chaves de eventos ou ["*"] para todos os eventos. A lista completa está no Tillor em Conta → Programadores, em Adicionar webhook → Eventos subscritos.

Alguns eventos ocorrem com tanta frequência que não os pode escolher e que também não chegam através de *, como o estado físico das cancelas, a escrita na caixa de entrada, os registos de controladores e a presença de veículos. Esses não constam da lista abaixo. Os eventos que pode escolher dependem também das suas permissões.

• enabled - true para ativar a entrega

Só pode escolher eventos para os quais o seu membro da organização tenha a permissão adequada (por ex. transações bancárias para bankAccountTransaction:*). O wildcard * só está disponível para membros com acesso total (*). Perante uma combinação inválida, a API devolve um erro. Um webhook reencaminha o payload completo, com os dados associados (como o cliente numa reserva). Por isso, tem de poder ler também esses domínios para criar um webhook, alterar o URL ou os eventos, ou voltar a ativá-lo.

Payload do webhookCopiar a ligação para esta secção

Cada entrega de webhook é um POST com:

Cabeçalhos:

• Content-Type: application/json
• X-Webhook-Event-ID - ID único estável desta entrega lógica (o mesmo valor nas novas tentativas)
• X-Webhook-Signature - assinatura HMAC-SHA256 do corpo, formato sha256=<hex> (consulte Verificar a assinatura)

Corpo:

{
  "event": "invoice:created",
  "data": {},
  "timestamp": 1735689600000,
  "traceId": "4bf92f3577b34da6a3ce929d0e0e4736",
  "spanId": "00f067aa0ba902b7",
  "triggeredBy": {
    "id": "usr_63x8jp68is",
    "name": "Niels"
  }
}

Consulte Exemplos para exemplos completos de payload.

Verificar a assinaturaCopiar a ligação para esta secção

Cada webhook tem o seu próprio segredo de assinatura (64 carateres hexadecimais, visível na tabela de webhooks em Mostrar segredo de assinatura em Conta → Programadores). O Tillor assina cada POST com esse segredo para que possa verificar que o pedido vem mesmo do Tillor e que o corpo não foi alterado.

Como o Tillor assina:

1. Calcula HMAC-SHA256(signingSecret, raw_request_body) (hexadecimal em minúsculas).
2. Envia-o como X-Webhook-Signature: sha256=<hex>.

Como verifica:

1. Leia o corpo bruto do pedido (antes do parse de JSON - caso contrário o hash não coincide).
2. Calcule você mesmo HMAC-SHA256(signingSecret, raw_body) em hexadecimal.
3. Compare com o valor a seguir a sha256= no cabeçalho X-Webhook-Signature com uma comparação de tempo constante.

import crypto from "node:crypto";

function verifyTillorWebhook(rawBody, headerSignature, signingSecret) {
  const expected = crypto.createHmac("sha256", signingSecret).update(rawBody).digest("hex");
  const received = headerSignature.replace(/^sha256=/, "");
  const a = Buffer.from(expected, "hex");
  const b = Buffer.from(received, "hex");
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

Comportamento de entrega e novas tentativasCopiar a ligação para esta secção

• Responda com um estado 2xx para confirmar o sucesso.
• Numa entrega falhada (não 2xx, erro de rede ou destino bloqueado), o Tillor volta a tentar a entrega automaticamente com intervalos cada vez maiores. Cada tentativa reutiliza o mesmo payload, a mesma assinatura e o mesmo ID de evento (idempotente).

• Se uma das tentativas tiver sucesso (2xx) → a entrega está concluída.
• Se também a tentativa 10 (após 24 h) falhar → a entrega é marcada definitivamente como falhada e não volta a ser tentada.
• Se entretanto o webhook for desativado, o Tillor deixa de tentar de novo.

Notificações em caso de falhas persistentesCopiar a ligação para esta secção

Se as entregas de um endpoint de webhook continuarem a falhar, o Tillor envia no máximo duas notificações por incidente (por endpoint):

1. Após 5 minutos de falhas persistentes - e-mail para o endereço de e-mail da organização (supportEmail, caso contrário email) e para os membros da organização com direitos para alterar as definições da organização, mais push (se estiver ativado) para esses membros. O e-mail indica desde quando as entregas falham. As datas no e-mail usam o fuso horário de Definições > Geral (por defeito Europe/Brussels).
2. Em caso de falha definitiva - os mesmos destinatários recebem uma notificação quando o primeiro evento desse incidente é marcado como definitivamente falhado após todas as tentativas.

Não recebe uma notificação por cada evento falhado. Assim que todas as entregas falhadas de um endpoint forem resolvidas (entregues com sucesso), um incidente seguinte recomeça com as mesmas regras.

Em Conta → Programadores, a tabela de webhooks mostra por endpoint um estado de entrega compacto (números de entregas à espera de nova tentativa e definitivamente falhadas). Clique no ícone ℹ para detalhes, incluindo a mensagem de erro completa e o payload da tentativa mais recente.

• Repetir entregas falhadas (↻): apenas as entregas definitivamente falhadas desse webhook.
• Forçar repetição (⚡): todas as entregas em espera e definitivamente falhadas desse webhook, independentemente dos tempos de espera planeados. O Tillor inicia isto em segundo plano para que filas grandes (por ex. milhares de eventos) sejam processadas em segurança.
• Forçar repetição de todos, em cima à direita ao lado de Adicionar webhook: o mesmo para todos os webhooks ativados na organização.

Tipos de eventosCopiar a ligação para esta secção

As chaves de eventos usam o formato entity:action ou entity:subresource:action. A lista completa, com a permissão de cada evento e um exemplo de payload, está no Índice de eventos. Essa página é gerada a partir do código e por isso está sempre completa. As mesmas chaves estão no Tillor em Conta → Programadores, em Adicionar webhook → Eventos subscritos.

Webhooks vs SSECopiar a ligação para esta secção

RelacionadoCopiar a ligação para esta secção

• OpenAPI - Especificação completa da API
• API HTTP - API REST e chaves de API
• SSE - Os mesmos eventos através de Server-Sent Events
• Automatizações - Enviar mensagens próprias a partir de uma automatização