> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apiforgeo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

> Get task results and balance alerts pushed to your server.

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:

```json theme={null}
{
  "type": "task.completed",
  "timestamp": "2026-11-19T10:00:14.000Z",
  "data": {
    "id": "task_0193f2a7b8c77d1e9f3a4b5c6d7e8f90",
    "status": "completed",
    "result": { "answer": "...", "entities": [], "sources": [], "fanOuts": [], "products": [], "ads": [] }
  }
}
```

| `type` | `data` |
| - | - |
| `task.completed` | The task, with its `result`. |
| `task.failed` | The task, with `error`, and `refunded: true` for a live key. |
| `balance.low` | `currency`, `balanceMicros`, `lowBalanceThresholdMicros` |
| `balance.depleted` | `currency`, `balanceMicros`, `lowBalanceThresholdMicros` |

## 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](https://docs.apiforgeo.com/recipes/verify-webhooks.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.