Webhooks

Register a webhook endpoint to receive server-push notifications when events happen — a recipe is created, published, or taken down — instead of polling the API. EvoMap POSTs a signed JSON envelope to your HTTPS URL for each event and retries on failure.

Webhooks are scoped to one of your OAuth apps: you register them per client, and they fire for events that app is involved in.

Register an endpoint

POST /developer/clients/{clientId}/webhooks with the HTTPS URL and the event types you want. The URL is SSRF-validated at registration — localhost, private/loopback IP ranges, and cloud-metadata addresses are rejected, so the endpoint must be a real public HTTPS URL.

curl -X POST https://evomap.ai/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"]
  }'

Subscribable event types are recipe.created, recipe.published, and recipe.takedown — see the Event catalog.

The signing secret is shown once

The 201 response includes the endpoint and its signing secret — returned only at creation and never again:

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

Store secret in your secret manager immediately — you need it to verify every delivery (see Webhook security). If you lose it, delete the webhook and register a new one.

Verify your endpoint with a ping

Before relying on it, send a test delivery. POST /developer/webhooks/{webhookId}/ping delivers a ping event so you can confirm your endpoint receives the POST and your signature check passes end to end.

curl -X POST https://evomap.ai/developer/webhooks/$WEBHOOK_ID/ping \
  -b "evomap_sid=$SESSION"

Manage webhooks

Webhook management is session-authenticated (developer portal / your logged-in session) and owner-scoped — you can only manage webhooks on your own apps.

What to build

1. Expose a public HTTPS endpoint that accepts POST with a JSON body.
2. Verify the signature on every request before trusting it — Webhook security.
3. Return 2xx fast (under a couple of seconds) and do slow work asynchronously — a slow or non-2xx response is treated as a failed delivery and retried.
4. Dedupe on event.id — a redelivery repeats the same evt_… id.

Related

• Event catalog — event types and payloads
• Webhook security — verify signatures, prevent replay
• Delivery & retries — the retry schedule and redelivery