Skip to main content
A webhook sends an event to your server when it happens. You do not need to poll.

Two ways to subscribe

  • Per task. Pass webhookUrl when you create a task. That URL gets the task’s task.completed or task.failed. These deliveries are signed with your organization’s task webhook secret, in the dashboard under Webhooks.
  • Endpoints. Add an endpoint in the dashboard, under Webhooks. It gets the event types you pick for it, for every task of the organization. Each endpoint has its own secret, shown when you add it or rotate it.
A webhook URL must use https. Else the API refuses it with 400 and the code webhook_url_invalid.

Events

Each delivery is a POST with a JSON body:

Answer fast

Answer with a 2xx status within 10 seconds. Do slow work after you answer, for example in a queue. Any other answer, or no answer, is a failure. The delivery is sent again after 5 seconds, 5 minutes, 30 minutes, then 2, 5, 10 and 10 hours. An endpoint that fails for all of those 27 hours is turned off, and the organization’s owners and admins get an email.

Drop duplicates

A retry can deliver the same event twice. The webhook-id header is the same on every retry of one event. Save the ids you processed, and skip an id you already have.

Verify the signature

Every delivery is signed, so you can prove that it came from API for GEO. Check the signature before you trust the body. See Verify webhook signatures.