Explicação: como e por que funciona assim
Esta página dá o modelo mental das integrações e o motivo das decisões. Não é passo a passo (veja o tutorial e os guias) nem lista de campos (veja a referência).
Duas portas, dois sentidos
O RSVP conversa com sistemas externos de duas formas complementares:
- API (pull): o terceiro pergunta quando quer saber. É a fonte da verdade sobre o estado atual.
- Webhook (push): o RSVP avisa quando algo muda. É o sinal de que vale olhar.
Elas se completam. O webhook diz "a resposta 42 mudou"; a API responde "como a resposta 42 está agora". Um receptor robusto trata o webhook como gatilho e, em caso de dúvida (perdeu eventos, chegou fora de ordem), reconcilia pela API. Por isso os dois falam o mesmo formato: o data de um webhook é o mesmo objeto que a API devolve, de modo que o terceiro escreve um só mapeamento.
Por que o token é da organização, e não de uma pessoa
Uma pessoa pode trabalhar em várias organizações e pode sair de uma delas. Um token de pessoa responderia mal a duas perguntas: de qual organização são os dados? E o que acontece com a integração quando a pessoa é desativada?
Com o token na organização, a resposta é direta: ele só enxerga a organização que o emitiu, e continua funcionando quando a equipe muda. O custo é que a organização passa a ser uma identidade autenticável, e que tokens de pessoa não servem na API (recebem 401). Quem emitiu o token fica registrado na auditoria como o autor.
O isolamento entre organizações não é automático no banco: o sistema não usa filtro global (decisão registrada na ADR 0021). Cada consulta da API parte da organização do token (Organization::apiEvents()), então um id de outra organização simplesmente não existe do ponto de vista do token e responde 404, nunca 403. Assim a API não confirma nem que o recurso existe.
Por que as permissões são separadas
events:read, rsvps:read e rsvps:write são independentes porque o risco é diferente. Ler eventos é público por natureza. Ler respostas expõe e-mails de pessoas. Escrever cria inscrições e consome vagas. Dar a um sistema só o que ele precisa limita o estrago se o token vazar. Por isso o painel pede a escolha explícita das permissões e recomenda um token por sistema.
De onde vêm os webhooks
Em vez de espalhar chamadas de webhook pelo código, as integrações se penduram na trilha de auditoria. Toda ação relevante (mudança de resposta, check-in, ciclo de vida do evento) já é registrada ali, dentro da mesma transação que a produziu. Um decorador (WebhookEmittingAuditTrail) observa esses registros e, quando o tipo é um dos assináveis, enfileira a entrega.
Consequências desejáveis:
- Cobertura única: qualquer caminho que mude o estado (formulário público, painel, importação, comando agendado que fecha eventos vencidos) passa pela auditoria, então todos geram webhook sem código extra.
- Consistência com o que foi gravado: se o fato não foi gravado, não há webhook. Se a transação é revertida, a entrega nem é enfileirada (ela só sai depois do commit).
- Falha isolada: um erro ao preparar o webhook é reportado, mas nunca derruba a ação de negócio. Uma pessoa não deixa de confirmar presença porque um terceiro está com problema.
O corpo é montado no instante do fato. Se a entrega precisar de retentativas, ela leva o retrato daquele momento, não o estado de quando finalmente chegou. Isso explica por que dois eventos podem chegar fora de ordem: o primeiro pode estar em retentativa enquanto o segundo passa direto.
Entrega: pelo menos uma vez, sem ordem
Redes falham. O sistema promete pelo menos uma vez: se o receptor não responde com sucesso, a entrega é repetida (cinco tentativas, com espera crescente de 1 min a 1 h). A contrapartida inevitável é que um evento pode chegar duas vezes, por exemplo quando o receptor processou mas a resposta se perdeu no caminho.
A alternativa, "no máximo uma vez", perderia eventos em falhas transitórias, o que é pior para quem integra pagamento, presença ou lista de espera. Por isso a responsabilidade de deduplicar fica com o receptor, e o contrato ajuda: o id da entrega é o mesmo em todas as tentativas.
Tampouco há garantia de ordem. Ordenar exigiria que uma entrega presa bloqueasse todas as seguintes. Receptores devem tratar cada evento como "o estado da resposta era X naquele momento" e, quando a ordem importa, consultar a API para o estado atual.
Quando o receptor fica fora do ar
Cinco entregas esgotadas seguidas desativam o endpoint. O limite protege os dois lados: o RSVP não fica tentando indefinidamente um endereço morto, e quem opera o receptor não é inundado de tráfego quando volta. O preço é que, depois de desativado, nada é reenviado e é preciso recadastrar o webhook. Quem precisa de garantia forte deve, ao voltar, reconciliar pela API (listar as respostas do evento).
Uma entrega bem-sucedida zera a contagem. Falhas esparsas, no meio de muitos sucessos, nunca desativam nada.
Um detalhe sutil: redirecionamentos (3xx) não são seguidos e não contam como falha. O sistema considera que o receptor respondeu. Quem migra o endereço do receptor por redirecionamento perde eventos em silêncio; o certo é atualizar a URL cadastrada.
Por que o webhook recusa algumas URLs
Um webhook faz o servidor do RSVP abrir uma conexão para um endereço escolhido por quem cadastra. Sem cuidado, isso vira uma porta para atacar o que só o servidor alcança: serviços internos, bancos, e o endereço de metadados da nuvem (169.254.169.254), que costuma entregar credenciais. Essa classe de ataque se chama SSRF.
Por isso:
- https obrigatório: o conteúdo carrega e-mails de pessoas e não deve trafegar em claro.
- Só endereços públicos: se o host resolve para qualquer IP privado, de loopback, link-local ou reservado, a URL é recusada. A checagem cobre IPv6 e o truque de embutir IPv4 em IPv6.
- Sem credenciais na URL: elas vazariam em logs.
- Checagem repetida na entrega e conexão fixada: um atacante poderia cadastrar um domínio que resolve para um IP público e, depois, trocar o DNS para um IP interno (DNS rebinding). Por isso o endereço é verificado de novo a cada entrega e a conexão é feita nos IPs que acabaram de ser validados, sem nova resolução.
- Sem redirecionamentos: um servidor público poderia redirecionar para um endereço interno e contornar a checagem.
O efeito colateral que surpreende no desenvolvimento: não dá para apontar um webhook para localhost ou para uma máquina da rede local. Use um receptor público de teste ou um túnel https.
Por que o segredo aparece uma vez
O token e o segredo são credenciais. Mostrá-los apenas na criação reduz o que um acesso futuro ao painel (uma sessão esquecida, um ombro curioso) consegue extrair. Internamente o token só é guardado em forma de hash (não dá para recuperá-lo) e o segredo do webhook é guardado cifrado, porque o sistema precisa dele para assinar, mas nunca o exibe de novo. O custo é conhecido: perdeu, recria. Também por isso não existe "rotação no lugar": o desenho é de substituir uma credencial por outra, com um período de convivência, e não de editar a existente.
A auditoria guarda o nome do token e só o host do webhook; nunca o segredo e nunca a URL completa, que pode conter identificadores sensíveis no caminho.
Por que a assinatura inclui o timestamp
Assinar só o corpo permitiria que alguém que capturou uma entrega legítima a reenviasse depois ("replay"), e o receptor a aceitaria. Ao assinar timestamp.corpo e pedir que o receptor rejeite timestamps antigos, uma captura só vale por poucos minutos. O timestamp é o da tentativa, então retentativas legítimas, que acontecem horas depois, são assinadas de novo com horário atual e continuam válidas. A deduplicação por id, e não pelo timestamp, é o que evita processar duas vezes.
Assinar bytes exatos do corpo (e não "o JSON") evita ambiguidades de formatação: dois JSONs equivalentes têm bytes diferentes.
Privacidade
A API e os webhooks expõem o e-mail de quem respondeu, porque é o identificador natural em integrações (CRM, listas de e-mail). O telefone nunca sai, nem pela API nem por webhook, e a API não aceita telefone na inscrição. A coleta de telefone é controlada por configuração da plataforma e tem regras próprias de privacidade; mantê-lo fora das integrações evita que um token de integração vire uma fonte de dados mais sensíveis do que o necessário.
Quem recebe o e-mail passa a ser, por sua vez, responsável por ele. Quando a rotina de retenção anonimiza um evento encerrado, o e-mail some da resposta no RSVP (a API devolve email: null e guest_name vira um marcador), mas cópias já entregues a terceiros não são recolhidas: isso precisa ser tratado entre a organização e o terceiro.
Limites e o que ficou de fora
Escolhas deliberadas de simplicidade, com o que fazer se não bastarem:
| Limite hoje | Consequência | Evolução possível |
|---|---|---|
| Sem histórico de entregas no painel | Diagnóstico por logs do receptor e queue:failed |
Tabela de entregas com status e botão de reenvio |
| Sem reativação nem rotação de segredo | Remover e recadastrar | Ação de reativar e segredo duplo temporário |
| Sem reenvio de eventos perdidos | Reconciliar pela API | Reenvio por intervalo de datas |
| API somente leitura, exceto criar inscrição | Não há convites nem check-in pela API | Novas permissões e rotas, com seus próprios riscos |
| Tokens não expiram | Revogação manual | Expiração opcional por token |
| Limite único de 60 req/min | Integrações em lote precisam espaçar | Limite configurável por token |
| Webhooks só de saída | Terceiro não envia eventos para o RSVP | Endpoint de entrada com assinatura, se surgir a necessidade |
Peças envolvidas
Para quem vai ler o código: o fluxo de um webhook é AuditTrail::record → WebhookEmittingAuditTrail → WebhookDispatcher (escolhe endpoints ativos que assinam o tipo) → WebhookPayloads (monta o corpo com os mesmos Resources da API) → job DeliverWebhook (valida a URL de novo, assina com WebhookSigner, envia, registra sucesso ou falha). A fila precisa de um worker rodando; sem ele, as entregas ficam esperando. A visão de arquitetura resumida está em architecture.md.