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

# Webhook events

> Communication between gotoHuman and you agents and workflows is based on webhooks.

### Webhook requests

The webhook is a `POST` request to your endpoint ([agent](/agent-setup#agent-webhook) or [tool](/create-template#tool-webhook)) with `Content-Type: application/json`.

<Info>
  Values in `reviewResult.data` follow the same shape as the `data` object in your [review request](/send-requests) — plus any reviewer edits or selections.
</Info>

### Events

**Review completed** (`event: "review.completed"`):

```json theme={null}
{
  "event": "review.completed",
  "accountId": "abFMvLv4HafQymWxKDAov",
  "reviewId": "123456abcdef",
  "agentId": "agent123456abcdef",
  "sessionId": "session789abcdef",
  "formId": "123456abcdef",
  "formName": "Review AI Draft",
  "reviewResult": {
    "response": "approved",
    "respondingUser": "jess@acme.org",
    "respondedAt": "2024-10-05T14:48:00.000Z",
    "data": {
      "blogPost": "Regarding the very interesting topic of...",
      "rating": 7.5,
      "decisionSelect": "approve"
    }
  },
  "meta": {
    "example": "LLM thread id"
  },
  "gthLink": "https://app.gotohuman.com/accounts/abFMvLv4HafQymWxKDAov/inbox/agents/all/reviews/123456abcdef"
}
```

**Trigger form submitted** (`event: "trigger.submitted"`):

Similar structure, but omits some fields:

```json theme={null}
{
  "event": "trigger.submitted",
  "accountId": "abFMvLv4HafQymWxKDAov",
  "reviewId": "123456abcdef",
  "formId": "abcdef123456",
  "formName": "Start workflow",
  "reviewResult": {
    "respondingUser": "jess@acme.org",
    "respondedAt": "2024-10-05T14:48:00.000Z",
    "data": {
      "taskDescription": "Summarize the Q3 board deck"
    }
  },
  "gthLink": "https://app.gotohuman.com/accounts/abFMvLv4HafQymWxKDAov/inbox/agents/all/reviews/123456abcdef"
}
```

| Property                      | Description                                                                                           |
| ----------------------------- | ----------------------------------------------------------------------------------------------------- |
| `event`                       | `review.completed` or `trigger.submitted`                                                             |
| `reviewResult.data`           | Values after review — same structure as your request `data`                                           |
| `reviewResult.response`       | `approved` or `rejected` (review forms only)                                                          |
| `reviewResult.respondingUser` | Email of the reviewer who submitted                                                                   |
| `reviewResult.respondedAt`    | ISO 8601 timestamp                                                                                    |
| `sessionId`                   | Workflow session id, when the review is part of a session                                             |
| `meta`                        | Echo of any `meta` you sent with the request                                                          |
| `fileCache`                   | Map of original media URLs to CDN URLs — see [Images and videos](/images-videos#cdn-urls-in-webhooks) |
| `gthLink`                     | Link to open the review in gotoHuman                                                                  |

**Chat message sent** (`event: "session.human_message"`):

Sent whenever a team member sends a message in a [chat agent](/chat-agents) session:

```json theme={null}
{
  "event": "session.human_message",
  "accountId": "abFMvLv4HafQymWxKDAov",
  "agentId": "agent123456abcdef",
  "sessionId": "session789abcdef",
  "message": "Please make the tone more formal.",
  "createdAt": "2024-10-05T14:48:00.000Z"
}
```

| Property    | Description                          |
| ----------- | ------------------------------------ |
| `event`     | `session.human_message`              |
| `agentId`   | Chat agent id                        |
| `sessionId` | Id to resume the session from memory |
| `message`   | Message text                         |

### Retries

Our webhook delivery follows an **at-least-once** approach: we retry until your endpoint returns a successful HTTP response, or until automatic retries are exhausted.

Failed deliveries are **retried automatically** — up to 7 attempts in total, with exponential backoff between tries (about 1 minute, 5 minutes, 15 minutes, 45 minutes, 2 hours, then 6 hours).

You can monitor delivery status in the review history. You can **stop** auto-retries from there if needed or trigger another delivery **manually** — for example after fixing your endpoint.

### Idempotency

In rare cases, the same event may be delivered more than once. This can happen when your server processed the request but we did not receive a timely success response — for example due to a network error, a timeout, or a non-2xx status code returned after your handler already ran. When that happens, we treat the delivery as failed and **schedule a retry**.

Retriable logic and workflows must therefore be **idempotent**: downstream side effects must be safe to replay. Setting the same value on a database row twice is usually harmless; sending an email twice is not.

#### Idempotency key header

One strategy to ensure webhook events are processed **exactly once** is to persist state somewhere recording that a given event ID has already been processed. For that purpose we provide an `Idempotency-Key` header in each webhook event. The value is unique to that delivery and stays the same across automatic and manual retries.

Before running side effects, check whether you have already processed that key. If so, return a success response without repeating the work.

### n8n

If you are using n8n to build your AI workflow, read how to handle completed reviews in our [n8n integration guide](/Integrations/n8n).

### Make

When using Make to create your workflow, read our [Make integration guide](/Integrations/make-com) on how to handle submitted reviews.