Webhooks

Em vez de perguntar à API de tempos em tempos se algo mudou, você pode deixar o Festero avisar. Cada vez que um orçamento é aceito, uma parcela é paga ou uma visita é marcada, o Festero faz uma requisição POST para o endereço HTTPS do seu sistema, com um resumo do que aconteceu.

O aviso é enxuto de propósito: traz o tipo do evento, identificadores, situação e datas. O detalhe você busca na API, com a sua credencial, pelo resource_url que vem no próprio aviso. Assim o webhook nunca vaza mais do que a API permite ler.

Visão geral

1. Você cadastra o endereço e escolhe os eventos na tela API do Festero.
2. O Festero envia um teste (ping). Quando o seu endereço responde 2xx, ele fica Ativo.
3. A partir daí, cada evento escolhido vira uma requisição assinada para o seu endereço.
4. Você verifica a assinatura, responde 2xx rápido e processa depois.
5. Se o seu endereço falhar, o Festero tenta de novo, com intervalos crescentes.

Quais eventos existem e o que cada um traz: Eventos de webhook. Como conferir a assinatura, com código em Node, Python e C#: Verificar a assinatura.

Cadastrar o endereço

Webhooks fazem parte dos planos Premium e Enterprise. Quem tem a permissão Gerenciar a API pública e as chaves MCP cadastra o endereço na seção Webhook da tela API do Festero (item do menu lateral), em Cadastrar endereço.

Campo	Regra
Endereço (URL)	Começa com https://, usa a porta padrão 443, sem usuário e senha, sem # (fragmento) e com um nome de domínio público (não um número de IP, nem localhost, .local ou .internal). Até 2.048 caracteres.
Eventos	Pelo menos um. Você só vê para assinar os eventos dos dados que você mesmo enxerga no Festero.

Outras regras:

• Um endereço por empresa. Para mudar, edite o atual.
• O domínio precisa apontar para a internet pública. O Festero recusa endereços que resolvem para redes internas, e confere o destino de novo a cada envio.
• O Festero não segue redirecionamentos. Cadastre o endereço final: uma resposta 3xx conta como falha.
• O segredo aparece uma única vez, ao cadastrar. Copie e guarde: ele é a chave para verificar a assinatura. Se perder, use Gerar novo segredo.

Guarde o segredo agora

O segredo de assinatura (começa com whsec_) é mostrado só na criação e a cada troca. Depois de fechar a janela, não dá para vê-lo de novo.

Teste e ativação

Ao cadastrar, o endereço fica com o status Aguardando teste e o Festero envia um evento ping, assinado como qualquer outro. O endereço passa a Ativo quando responde 2xx a um ping. Antes disso, nenhum evento real é enviado.

• Para repetir o teste, clique em Enviar teste.
• Trocar a URL do endereço faz ele voltar a Aguardando teste, porque a URL nova ainda não provou que é sua.
• O ping não conta como falha do endereço e não entra no limite por hora.

Veja o ping em Eventos de webhook.

A requisição que você recebe

POST /webhooks/festero HTTP/1.1
Host: seusistema.com.br
Content-Type: application/json; charset=utf-8
User-Agent: Festero-Webhooks/1.0
Festero-Event: quote.accepted
Festero-Event-Id: c0a8e5b2-3f41-4d7a-9b16-2e8d5a7f1c04
Festero-Delivery-Id: 4b1e7d30-9a52-4c86-b3f0-2d8a6e1c5f97
Festero-Attempt: 1
Festero-Signature: t=1792593128,v1=b6de473caad2e5bc13c7df4254a8c1f8f9af543e99cadc5bb19b160083f20eee

{"event_id":"c0a8e5b2-3f41-4d7a-9b16-2e8d5a7f1c04","type":"quote.accepted","occurred_at":"2026-10-21T14:32:08.4519833Z","workspace_id":"0f8fad5b-d9cb-469f-a165-70867728950e","api_version":"v1","resource_url":"https://platform.festero.com.br/v1/quotes/e4f6a9b2-3c71-4d85-9b0e-7a1c5d8f2634","data":{"id":"e4f6a9b2-3c71-4d85-9b0e-7a1c5d8f2634","status":"approved","event_id":"b7e2c4a1-95d3-4f08-a6b2-1c8d3e5f7a90"}}

Cabeçalho	Significado
Festero-Event	O tipo do evento, por exemplo quote.accepted.
Festero-Event-Id	Identificador do evento. Não muda entre reentregas e é igual ao event_id do corpo. Use-o para deduplicar.
Festero-Delivery-Id	Identificador da entrega do evento ao seu endereço.
Festero-Attempt	Número da tentativa: 1 na primeira e 2, 3... nas reentregas.
Festero-Signature	A assinatura: t=<unix>,v1=<hex>. Durante a troca do segredo, traz também v1_prev.
Content-Type	application/json.
User-Agent	Festero-Webhooks/1.0.

O corpo é o envelope JSON descrito em Eventos de webhook. A verificação da assinatura usa esses bytes exatamente como chegaram.

O que responder

Responda com qualquer status 2xx em até 10 segundos. O corpo da sua resposta é ignorado.

• Responda primeiro, processe depois. Verifique a assinatura, grave o aviso numa fila e devolva 200. Trabalho demorado dentro da requisição estoura os 10 segundos e vira falha.
• Qualquer outra coisa conta como falha: 3xx, 4xx, 5xx, demora além de 10 segundos, ou falha de conexão ou de TLS.

Reentregas

Se o seu endereço não responde 2xx, o Festero tenta de novo, com intervalos crescentes. O mesmo evento volta com o mesmo Festero-Event-Id, o Festero-Attempt aumentado e uma assinatura nova (o t é o instante da nova tentativa).

Tentativa que falhou	Próxima tentativa
1ª	depois de 1 minuto
2ª	depois de 5 minutos
3ª	depois de 30 minutos
4ª	depois de 2 horas
5ª	depois de 6 horas
6ª	depois de 24 horas
7ª	nenhuma: a entrega é abandonada

São, portanto, 7 tentativas (a primeira e 6 reentregas) ao longo de cerca de 33 horas. Casos especiais:

• Resposta 410 (Gone): o Festero entende que o endereço não existe mais, abandona a entrega na hora e conta isso como 3 falhas.
• Falha do lado do Festero (por exemplo, uma indisponibilidade nossa): a nova tentativa sai em 1 minuto e não conta contra o seu endereço nem entra nas 7 tentativas.
• Reenviar: na tabela Entregas recentes da tela, o botão Reenviar manda de novo um evento entregue, que falhou ou que foi abandonado, desde que tenha até 7 dias.

Uma entrega abandonada não é perdida para sempre: o dado continua na API. Busque o recurso pelo resource_url ou pelo filtro updatedSince.

Desativação automática

Um endereço que falha demais é desativado, para o Festero não insistir num destino fora do ar. A regra, que precisa ser cumprida nas duas partes:

1. 10 falhas seguidas do seu endereço (cada tentativa que falha conta; o 410 conta por 3), e
2. a primeira dessas falhas aconteceu há mais de 24 horas.

Qualquer resposta 2xx zera a contagem. Falhas do Festero e do ping não contam.

Quando isso acontece:

• o status do endereço passa a Desativado e as pessoas com a permissão de gerenciar a API recebem uma notificação no Festero;
• os eventos que acontecem enquanto ele está desativado não são enviados depois. Para recuperar o período, consulte a API com updatedSince (veja Paginação e datas);
• depois de corrigir o seu sistema, clique em Reativar. Se a URL já foi testada antes, ele volta direto a Ativo; senão, volta a Aguardando teste.

Você também pode Desativar o endereço manualmente, a qualquer momento.

Teto por hora

Cada endereço recebe no máximo 3.000 entregas por hora. Uma janela de uma hora começa na primeira entrega e se renova quando passa uma hora. O excedente não é descartado: as entregas ficam com o status Adiada pelo limite por hora e saem quando a janela seguinte abre.

Se o acúmulo passa de 10.000 entregas adiadas, ou a mais antiga espera há mais de 24 horas, o endereço é desativado com o motivo "passou do limite de entregas por hora". As entregas pendentes ficam guardadas e seguem quando você reativa.

Idempotência e ordem

• O mesmo aviso pode chegar mais de uma vez, por reentrega ou por duplicidade na entrega. Guarde os Festero-Event-Id já processados e ignore os repetidos. Seu processamento deve dar o mesmo resultado se rodar duas vezes.
• A ordem é a melhor possível, mas não é garantida, nem entre eventos de recursos diferentes. Um aviso reentregue chega depois de outros mais novos. Em vez de confiar na ordem de chegada, busque o estado atual pelo resource_url.

O resource_url

Todo aviso traz o endereço do recurso na API, por exemplo https://platform.festero.com.br/v1/quotes/e4f6a9b2-.... Chame-o com Authorization: Bearer <token>, como qualquer rota da API.

• Você recebe o estado de agora, que pode ser mais novo do que o do aviso.
• A sua credencial precisa ter o escopo do recurso (quotes:read para um orçamento, e assim por diante). Veja a tabela em Eventos de webhook.
• Um recurso excluído responde 404 (por exemplo, depois de um event.cancelled com reason igual a deleted).

Trocar o segredo

Em Gerar novo segredo, o Festero cria um segredo novo e o mostra uma única vez. O anterior continua valendo por 24 horas, e os avisos desse período trazem as duas assinaturas (v1 e v1_prev). Detalhes e código em Verificar a assinatura.

Acompanhar as entregas

A tabela Entregas recentes da seção Webhook mostra cada entrega, com o status:

Status na tela	Significado
Na fila	Aguardando envio.
Enviando	A requisição está a caminho.
Entregue	Seu endereço respondeu 2xx.
Falhou, vai tentar de novo	Há uma nova tentativa agendada.
Abandonada	Esgotou as 7 tentativas, ou o endereço respondeu 410.
Adiada pelo limite por hora	Passou do teto de 3.000 por hora e sai na próxima janela.

Ao abrir uma linha, você vê cada tentativa, com o código que o seu endereço respondeu, a duração e de quem foi a falha: Falha do seu endereço ou Falha do Festero (não conta contra o seu endereço). O Festero não guarda o corpo das respostas do seu endereço.

Contrato de entrega, em resumo

Item	Valor
Requisição	POST com corpo JSON e Content-Type: application/json. Somente HTTPS na porta 443.
Cabeçalhos	Festero-Event, Festero-Event-Id, Festero-Delivery-Id, Festero-Attempt e Festero-Signature: t=<unix>,v1=<hex>. Na troca do segredo, também v1_prev, por 24 horas.
Verificação	HMAC-SHA256 de "<t>.<corpo bruto>" com o segredo do endereço, comparado em tempo constante. Recuse se t estiver a mais de 5 minutos do relógio do seu servidor (em reentregas, t é o instante da tentativa).
Resposta esperada	Qualquer 2xx em até 10 segundos. O corpo é ignorado. Responda primeiro e processe depois.
Idempotência	O mesmo evento pode chegar mais de uma vez: deduplique por Festero-Event-Id.
Ordem	Melhor esforço, nunca garantida.
Reentregas	7 tentativas, com 1 min, 5 min, 30 min, 2 h, 6 h e 24 h entre elas. Redirecionamentos não são seguidos.
Desativação	10 falhas seguidas, a primeira há mais de 24 horas. Reativável na tela API do Festero.
Teto	3.000 entregas por hora por endereço. O excedente é adiado para a hora seguinte, sem descartar.
Segredo	Mostrado uma vez ao criar e ao trocar.

Checklist do seu endereço

• [ ] Responde 2xx em poucos segundos, sem processar dentro da requisição.
• [ ] Lê o corpo como bytes brutos e verifica a assinatura.
• [ ] Recusa assinatura inválida e t fora de 5 minutos.
• [ ] Deduplica por Festero-Event-Id.
• [ ] Busca o estado atual pelo resource_url em vez de confiar só no payload.
• [ ] Tem um jeito de recuperar o que perdeu, com a API e updatedSince, caso fique fora do ar.