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
- Revogar um token
- Cadastrar um webhook
- Verificar a assinatura de um webhook
- Receber webhooks sem processar duas vezes
- Testar um webhook
- Voltar a receber de um webhook desativado
- Trocar o segredo de um webhook
- Remover um webhook
- Descobrir por que uma entrega falhou
- Registrar uma inscrição com campos personalizados
- Percorrer todas as páginas de uma listagem
Criar um token de API
- Abra Integrações → Tokens da API.
- Dê um nome que diga quem usa (
crm-producao, nãotoken1), pois o nome é o que aparece na lista e na auditoria. - Marque só as permissões necessárias (
events:read,rsvps:read,rsvps:write). Um sistema que só mostra eventos não precisa dersvps:write. - 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
- 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
- Integrações → Webhooks.
- Informe a URL. Ela precisa ser https e apontar para um endereço público (veja por quê).
- Marque os tipos de evento que o sistema quer. Assine só o necessário: cada tipo a mais é tráfego e processamento a mais.
- 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:
- Leia o corpo bruto da requisição, byte a byte, antes de qualquer parse de JSON.
- Leia
X-Webhook-Timestampe rejeite se estiver a mais de 5 minutos do seu relógio. - Calcule
HMAC-SHA256da string"{timestamp}.{corpo}"com o segredo, em hexadecimal, e prefixe comsha256=. - Compare com
X-Webhook-Signatureem 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.
- Guarde os
idjá processados (tabela com índice único, ou chave com expiração de alguns dias). - Ao receber, tente inserir o
id. Se já existir, responda200e não processe de novo. - Responda
2xxrápido (o prazo é de 10 segundos) e faça o trabalho pesado em segundo plano. Status4xx/5xxou demora contam como falha e geram nova tentativa. Um3xxnã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
- Integrações → Webhooks → Enviar teste na linha do endpoint.
- O receptor recebe um evento
pingcom 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.
- Corrija a causa no receptor (URL fora do ar, certificado vencido, respostas
4xx/5xx). - Remova o endpoint desativado.
- 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):
- Cadastre um segundo webhook com a mesma URL e os mesmos tipos. Anote o novo segredo.
- Faça o receptor aceitar os dois segredos (tente um, depois o outro).
- Remova o webhook antigo.
- 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
- 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:
- Lista de webhooks: "desativado após falhas seguidas" indica 5 falhas finais seguidas.
- Logs do receptor: procure o
X-Webhook-Id. Se não aparece, a requisição não chegou (DNS, firewall, certificado, URL). - Fila de falhas (quem opera o servidor):
php artisan queue:failedlista as entregas esgotadas, com a exceção (status HTTP, timeout, "URL do webhook não é mais segura para entrega"). - 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.