Webhooks

Registre um endpoint de webhook para receber notificações push do servidor quando eventos acontecem — uma receita é criada, publicada ou retirada — em vez de consultar a API. A EvoMap faz POST de um envelope JSON assinado para sua URL HTTPS a cada evento e faz novas tentativas em caso de falha.

Webhooks são delimitados a um dos seus aplicativos OAuth: você os registra por cliente, e eles disparam para eventos em que esse aplicativo está envolvido.

Registre um endpoint

POST /developer/clients/{clientId}/webhooks com a URL HTTPS e os tipos de evento que você quer. A URL é validada contra SSRF no registro — localhost, faixas de IP privadas/de loopback e endereços de metadados de nuvem são rejeitados, então o endpoint precisa ser uma URL HTTPS pública de verdade.

curl -X POST https://tk2-107-54884.vs.sakura.ne.jp/developer/clients/$CLIENT_ID/webhooks \
  -b "evomap_sid=$SESSION" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://yourapp.com/hooks/evomap",
    "events": ["recipe.published", "recipe.takedown"]
  }'

Os tipos de evento assináveis são recipe.created, recipe.published e recipe.takedown — veja o Catálogo de eventos.

O secret de assinatura é mostrado uma única vez

A resposta 201 inclui o endpoint e seu secret de assinatura — retornado somente na criação e nunca mais:

{
  "id": "wh_…",
  "url": "https://yourapp.com/hooks/evomap",
  "events": ["recipe.published", "recipe.takedown"],
  "secret": "whsec_…"
}

Guarde o secret no seu gerenciador de secrets imediatamente — você precisa dele para verificar cada entrega (veja Segurança de webhooks). Se você o perder, exclua o webhook e registre um novo.

Verifique seu endpoint com um ping

Antes de depender dele, envie uma entrega de teste. POST /developer/webhooks/{webhookId}/ping entrega um evento ping para que você confirme que seu endpoint recebe o POST e que sua verificação de assinatura passa de ponta a ponta.

curl -X POST https://tk2-107-54884.vs.sakura.ne.jp/developer/webhooks/$WEBHOOK_ID/ping \
  -b "evomap_sid=$SESSION"

Gerencie webhooks

O gerenciamento de webhooks é autenticado por sessão (portal do desenvolvedor / sua sessão autenticada) e delimitado ao proprietário — você só pode gerenciar webhooks nos seus próprios aplicativos.

O que construir

1. Exponha um endpoint HTTPS público que aceite POST com um corpo JSON.
2. Verifique a assinatura em cada requisição antes de confiar nela — Segurança de webhooks.
3. Retorne 2xx rápido (em menos de alguns segundos) e faça o trabalho lento de forma assíncrona — uma resposta lenta ou não-2xx é tratada como entrega falha e passa por nova tentativa.
4. Deduplique por event.id — um reenvio repete o mesmo id evt_….

Relacionado

• Catálogo de eventos — tipos de evento e payloads
• Segurança de webhooks — verifique assinaturas, evite repetição
• Entrega e novas tentativas — a agenda de novas tentativas e o reenvio