Seu sistema fica sabendo na hora.

Como funciona

• Você escolhe os eventos

  Cadastre um endereço em Configurações › Webhooks e marque só os eventos que interessam.

• Assinado

  Cada aviso traz uma assinatura feita com o segredo do webhook. Confira antes de confiar no conteúdo.

• Tenta de novo

  Se o seu endereço não responder, o aviso é reenviado algumas vezes, com intervalos cada vez maiores.

• Histórico e teste

  O painel mostra as últimas entregas e tem um botão para enviar um aviso de teste.

• Sem dados pessoais

  O aviso traz identificadores, situação e valores. Nada de CPF, documento, e-mail ou telefone.

• Liga com a API

  Use o identificador do aviso para buscar os detalhes pela API, com a sua chave.

Como conectar

1. 1

   Cadastre o endereço

   Em Configurações › Webhooks, toque em Novo webhook, informe um endereço https:// e escolha os eventos. Copie o segredo na hora.

2. 2

   Receba o aviso

   Cada evento chega como um POST com JSON. Responda com um status 2xx em até 10 segundos.

   POST https://seu-sistema.com/excursso
   X-Excursso-Event: payment.received
   X-Excursso-Signature: t=<unix>,v1=<assinatura>
   
   {
     "id": "<id-do-evento>",
     "type": "payment.received",
     "createdAt": "2030-01-10T12:00:00.000Z",
     "organizationId": "<id-da-agência>",
     "data": { "bookingId": "<id>", "amountCents": 15000 }
   }

3. 3

   Confira a assinatura

   Calcule um HMAC-SHA256 de t + "." + corpo com o segredo e compare com v1. Recuse avisos antigos pelo t.

   import { createHmac, timingSafeEqual } from "node:crypto"
   
   const [t, v1] = signature.split(",").map((part) => part.split("=")[1])
   const expected = createHmac("sha256", secret).update(`${t}.${body}`).digest("hex")
   const valid = timingSafeEqual(Buffer.from(expected), Buffer.from(v1))

4. 4

   Evite duplicidade

   Um aviso pode chegar mais de uma vez. Guarde o id do evento e ignore repetidos.

Eventos

Limites de hoje

• Só endereços https://. Redirecionamentos não são seguidos.
• Um webhook que falha várias vezes seguidas aparece como com falhas no painel, mas continua recebendo.
• O histórico de entregas fica disponível por 30 dias.