Tutorial: sua primeira integração
Ao final você terá: um token de API funcionando, uma inscrição criada por curl e um webhook assinado chegando em um receptor de teste.
Você precisa de: ser admin de uma organização no RSVP, um evento publicado com inscrição aberta e vagas, e curl. Tempo: cerca de 10 minutos.
Troque
https://rsvp.hellomanoel.compelo endereço da sua instalação nos comandos abaixo.
1. Crie um token de API
- Entre no painel e abra Integrações na barra lateral (
/admin/integracoes). - Em Tokens da API, informe o nome
tutoriale marque as três permissões:events:read,rsvps:read,rsvps:write. - Clique em Criar token.
- Copie o texto do token que aparece no topo da página. Ele tem a forma
1|abc...e não será exibido de novo.
Guarde-o numa variável do terminal:
export RSVP_TOKEN='1|cole-o-token-aqui'
export RSVP_URL='https://rsvp.hellomanoel.com'
2. Liste seus eventos
curl -s -H "Authorization: Bearer $RSVP_TOKEN" -H 'Accept: application/json' \
"$RSVP_URL/api/v1/events"
Você deve receber um JSON com data (lista de eventos) e links/meta de paginação. Anote o id do evento com inscrição aberta:
export EVENT_ID=1
Se a resposta for 401, o token está errado ou foi copiado incompleto.
3. Prepare um receptor de webhook
Você precisa de um endereço https público que aceite POST. Para o tutorial, use um receptor de teste como o webhook.site: abra o site e copie a URL única que ele mostra (https://webhook.site/...).
4. Cadastre o webhook
- Ainda em
/admin/integracoes, na seção Webhooks, cole a URL no campo URL (https). - Marque o evento
rsvp.status_changed. - Clique em Adicionar webhook.
- Copie o segredo de assinatura (
whsec_...) exibido. Ele também aparece uma única vez.
URLs
http://,localhost, IPs privados e endereços internos são rejeitados de propósito. Veja a explicação.
5. Envie um teste
Na linha do webhook, clique em Enviar teste. Em poucos segundos o receptor deve mostrar uma requisição POST com:
- corpo
{"id":"...","type":"ping","data":{"message":"ping"}}; - cabeçalhos
X-Webhook-Id,X-Webhook-Event,X-Webhook-TimestampeX-Webhook-Signature.
Se nada chegar, confira se o worker de fila está rodando (a entrega é feita pela fila).
6. Crie uma inscrição pela API
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}' \
"$RSVP_URL/api/v1/events/$EVENT_ID/rsvps"
Resposta esperada (201):
{"data":{"id":1,"event_id":1,"status":"confirmed","source":"direct_link","guest_name":"Ana Souza","email":"[email protected]", "...": "..."}}
Se o evento estiver lotado, status vem como waitlisted. Se o e-mail já estiver inscrito, a resposta é 202 e nada é criado.
7. Veja o webhook da inscrição
Volte ao receptor. Deve haver uma nova requisição rsvp.status_changed, com data.rsvp.status igual ao status da resposta e data.previous_status nulo (primeira resposta).
8. Confira a assinatura
No receptor, copie o corpo exatamente como recebido e os cabeçalhos X-Webhook-Timestamp e X-Webhook-Signature. Calcule o HMAC localmente com o segredo do passo 4:
TS='cole-o-timestamp'
BODY='cole-o-corpo-exato'
printf '%s' "$TS.$BODY" | openssl dgst -sha256 -hmac 'whsec_cole-o-segredo' | sed 's/^.* /sha256=/'
O resultado deve ser idêntico ao X-Webhook-Signature. Se for, você provou que a mensagem veio do RSVP e não foi alterada.
Pronto
Você criou um token, leu dados, escreveu uma inscrição e recebeu um evento assinado. Próximos passos:
- Verificar a assinatura em código no seu sistema: guia.
- Remover as credenciais do tutorial: guia e remover um webhook.
- Ver todos os campos e códigos: referência.