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.com pelo endereço da sua instalação nos comandos abaixo.

1. Crie um token de API

  1. Entre no painel e abra Integrações na barra lateral (/admin/integracoes).
  2. Em Tokens da API, informe o nome tutorial e marque as três permissões: events:read, rsvps:read, rsvps:write.
  3. Clique em Criar token.
  4. 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

  1. Ainda em /admin/integracoes, na seção Webhooks, cole a URL no campo URL (https).
  2. Marque o evento rsvp.status_changed.
  3. Clique em Adicionar webhook.
  4. 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-Timestamp e X-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: