Guias: como fazer

Receitas curtas para tarefas específicas. Para aprender do zero, use o tutorial. Para nomes exatos de campos e códigos, a referência.

Todas as ações de administração ficam em /admin/integracoes e exigem papel admin na organização corrente.

Criar um token de API

  1. Abra Integrações → Tokens da API.
  2. Dê um nome que diga quem usa (crm-producao, não token1), pois o nome é o que aparece na lista e na auditoria.
  3. Marque só as permissões necessárias (events:read, rsvps:read, rsvps:write). Um sistema que só mostra eventos não precisa de rsvps:write.
  4. Copie o token na faixa que aparece. Ele não é exibido de novo.

Use um token por sistema integrado. Assim você revoga um sem afetar os outros.

Revogar um token

  1. Integrações → Tokens da API → Revogar na linha do token.

Efeito imediato: a próxima chamada com ele recebe 401. A revogação fica na auditoria como integration.token_revoked.

Se um token vazou, revogue primeiro e crie o substituto depois.

Cadastrar um webhook

  1. Integrações → Webhooks.
  2. Informe a URL. Ela precisa ser https e apontar para um endereço público (veja por quê).
  3. Marque os tipos de evento que o sistema quer. Assine só o necessário: cada tipo a mais é tráfego e processamento a mais.
  4. Copie o segredo whsec_.... Ele não é exibido de novo.

Verificar a assinatura de um webhook

Sempre verifique antes de confiar no conteúdo. O algoritmo:

  1. Leia o corpo bruto da requisição, byte a byte, antes de qualquer parse de JSON.
  2. Leia X-Webhook-Timestamp e rejeite se estiver a mais de 5 minutos do seu relógio.
  3. Calcule HMAC-SHA256 da string "{timestamp}.{corpo}" com o segredo, em hexadecimal, e prefixe com sha256=.
  4. Compare com X-Webhook-Signature em tempo constante.

PHP

$body = file_get_contents('php://input');
$timestamp = $_SERVER['HTTP_X_WEBHOOK_TIMESTAMP'] ?? '';
$received = $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'] ?? '';

$expected = 'sha256='.hash_hmac('sha256', $timestamp.'.'.$body, $secret);

if (abs(time() - (int) $timestamp) > 300 || ! hash_equals($expected, $received)) {
    http_response_code(401);
    exit;
}

Node.js (Express)

import crypto from 'node:crypto';

app.post('/webhooks/rsvp', express.raw({ type: 'application/json' }), (req, res) => {
  const timestamp = req.get('X-Webhook-Timestamp') ?? '';
  const received = req.get('X-Webhook-Signature') ?? '';
  const expected = 'sha256=' + crypto.createHmac('sha256', SECRET)
    .update(`${timestamp}.`).update(req.body).digest('hex');

  const ok = received.length === expected.length
    && crypto.timingSafeEqual(Buffer.from(received), Buffer.from(expected))
    && Math.abs(Date.now() / 1000 - Number(timestamp)) <= 300;

  if (!ok) return res.sendStatus(401);
  const event = JSON.parse(req.body);
  res.sendStatus(200);
});

Python (Flask)

import hmac, hashlib, time
from flask import request, abort

@app.post("/webhooks/rsvp")
def rsvp_webhook():
    body = request.get_data()  # bytes brutos
    timestamp = request.headers.get("X-Webhook-Timestamp", "")
    received = request.headers.get("X-Webhook-Signature", "")
    expected = "sha256=" + hmac.new(
        SECRET.encode(), timestamp.encode() + b"." + body, hashlib.sha256
    ).hexdigest()

    if not hmac.compare_digest(expected, received) or abs(time.time() - int(timestamp)) > 300:
        abort(401)
    return "", 200

Erro comum: ler o JSON, reserializar e assinar o resultado. A ordem das chaves e os espaços mudam e a assinatura nunca confere. Assine sempre os bytes originais.

Receber webhooks sem processar duas vezes

A entrega é pelo menos uma vez: em retentativas, o mesmo evento pode chegar mais de uma vez. O id do corpo (e X-Webhook-Id) é o mesmo em todas as tentativas da mesma entrega.

  1. Guarde os id já processados (tabela com índice único, ou chave com expiração de alguns dias).
  2. Ao receber, tente inserir o id. Se já existir, responda 200 e não processe de novo.
  3. Responda 2xx rápido (o prazo é de 10 segundos) e faça o trabalho pesado em segundo plano. Status 4xx/5xx ou demora contam como falha e geram nova tentativa. Um 3xx não é seguido e conta como entregue: não deixe o endpoint redirecionar, ou os eventos se perdem sem aviso.

Também não conte com ordem: use data.rsvp.status como estado atual daquele evento e, se a ordem importar, compare responded_at/confirmed_at ou busque o estado atual pela API.

Testar um webhook

  1. Integrações → Webhooks → Enviar teste na linha do endpoint.
  2. O receptor recebe um evento ping com o corpo {"id":"...","type":"ping","data":{"message":"ping"}}, assinado como os demais.

O ping passa pela mesma fila e conta como falha se o receptor responder 4xx/5xx ou não responder em 10 segundos (veja o limite de falhas). O endpoint precisa estar ativo: um desativado ignora o teste.

Voltar a receber de um webhook desativado

Após 5 falhas finais seguidas o endpoint é desativado e a lista mostra "desativado após falhas seguidas". Não existe botão de reativar.

  1. Corrija a causa no receptor (URL fora do ar, certificado vencido, respostas 4xx/5xx).
  2. Remova o endpoint desativado.
  3. Cadastre de novo (a mesma URL serve). Você recebe um segredo novo: atualize-o no receptor.

Eventos ocorridos enquanto o endpoint estava desativado não são reenviados. Se precisar recuperar o estado, leia GET /api/v1/events/{id}/rsvps.

Trocar o segredo de um webhook

Não há rotação no lugar. Para trocar (por exemplo, o segredo vazou):

  1. Cadastre um segundo webhook com a mesma URL e os mesmos tipos. Anote o novo segredo.
  2. Faça o receptor aceitar os dois segredos (tente um, depois o outro).
  3. Remova o webhook antigo.
  4. Remova o segredo antigo do receptor.

Durante a transição o receptor recebe cada evento duas vezes (um por endpoint, com id diferentes). Para deduplicar por conteúdo, use data.rsvp.id + type + o estado, não o id da entrega.

Remover um webhook

  1. Integrações → Webhooks → Remover.

Entregas já na fila para esse endpoint são descartadas (o job não encontra o endpoint e termina sem enviar). Fica registrado webhook.deleted na auditoria com o host (não a URL completa).

Descobrir por que uma entrega falhou

O painel não guarda histórico de entregas. Pistas, da mais rápida à mais completa:

  1. Lista de webhooks: "desativado após falhas seguidas" indica 5 falhas finais seguidas.
  2. Logs do receptor: procure o X-Webhook-Id. Se não aparece, a requisição não chegou (DNS, firewall, certificado, URL).
  3. Fila de falhas (quem opera o servidor): php artisan queue:failed lista as entregas esgotadas, com a exceção (status HTTP, timeout, "URL do webhook não é mais segura para entrega").
  4. Auditoria (/admin/auditoria): confirma que o evento de domínio ocorreu e quando. O que está lá é o fato, não a entrega.

Causas frequentes: receptor responde 4xx/5xx, demora mais de 10 segundos, certificado inválido, ou o DNS passou a apontar para endereço privado. Atenção ao oposto: receptor que redireciona (3xx) não falha; a entrega é dada como concluída e o evento é perdido.

Registrar uma inscrição com campos personalizados

Se o evento tem perguntas extras, envie as respostas em fields, indexadas pelo id do campo:

curl -s -X POST -H "Authorization: Bearer $RSVP_TOKEN" \
  -H 'Accept: application/json' -H 'Content-Type: application/json' \
  -d '{
    "guest_name": "Ana Souza",
    "email": "[email protected]",
    "consent": true,
    "communications_consent": true,
    "fields": { "12": "Vegetariano", "13": ["Sexta", "Sábado"] }
  }' \
  "$RSVP_URL/api/v1/events/$EVENT_ID/rsvps"

Campos obrigatórios ausentes ou valores fora das opções voltam como 422 com a mensagem por campo (fields.12). communications_consent só é pedido quando o evento coleta esse consentimento.

Percorrer todas as páginas de uma listagem

As listagens são paginadas (15 itens por página). Siga links.next até ele ser null:

URL="$RSVP_URL/api/v1/events/$EVENT_ID/rsvps"
while [ -n "$URL" ] && [ "$URL" != "null" ]; do
  RESP=$(curl -s -H "Authorization: Bearer $RSVP_TOKEN" -H 'Accept: application/json' "$URL")
  echo "$RESP" | jq -c '.data[]'
  URL=$(echo "$RESP" | jq -r '.links.next')
done

Respeite o limite de 60 requisições por minuto por token. Ao receber 429, espere o tempo do cabeçalho Retry-After.