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

# Escalation Webhooks

> Configure webhooks that fire when a Genie escalates a conversation to a human agent.

Each Genie can have one active escalation webhook. When a call is escalated, HelpGenie sends a signed POST request to the configured URL with a customisable payload.

Webhook payloads are HMAC-SHA256 signed using your `secret`. The signature is sent in the `X-HelpGenie-Signature` header by default, or in the header name you specify via `secret_header`.

***

## Actions

### `get`

Returns the escalation webhook configured for a Genie, or `null` if none exists.

**Parameters**

| Field     | Type   | Required | Description |
| --------- | ------ | -------- | ----------- |
| `agentId` | string | Yes      | Genie UUID  |

**Response**

```json theme={null}
{
  "id": "webhook-uuid",
  "agent_id": "agent-uuid",
  "url": "https://example.com/webhook",
  "secret": "••••••••",
  "secret_header": "X-HelpGenie-Signature",
  "custom_fields": [],
  "is_active": true,
  "updated_at": "2024-01-01T00:00:00Z"
}
```

Returns `null` if no webhook is configured.

***

### `upsert`

Creates or updates the escalation webhook for a Genie. Only one webhook per Genie is supported — calling this again replaces the existing configuration.

**Parameters**

| Field           | Type    | Required | Description                                                                                                                                                         |
| --------------- | ------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `agentId`       | string  | Yes      | Genie UUID                                                                                                                                                          |
| `url`           | string  | Yes      | HTTPS endpoint to POST to on escalation                                                                                                                             |
| `secret`        | string  | No       | Shared secret used to sign the payload (HMAC-SHA256)                                                                                                                |
| `secret_header` | string  | No       | Header name for the signature, defaults to `X-HelpGenie-Signature`                                                                                                  |
| `custom_fields` | array   | No       | Custom payload field definitions. Each item can be a string key or an object `{ key, hint, useForSignature }`. When empty, a default set of standard fields is used |
| `is_active`     | boolean | No       | Whether the webhook is active, defaults to `true`                                                                                                                   |

**Default payload fields** (used when `custom_fields` is empty):

`eventId`, `eventType`, `timestamp`, `callerNumber`, `callSid`, `reason`, `summary`, `agentSessionId`

**Response** — the saved webhook row.

```json theme={null}
{
  "id": "webhook-uuid",
  "agent_id": "agent-uuid",
  "url": "https://example.com/webhook",
  "is_active": true
}
```

***

### `delete`

Removes the escalation webhook for a Genie. No-ops silently if no webhook exists.

**Parameters**

| Field     | Type   | Required | Description |
| --------- | ------ | -------- | ----------- |
| `agentId` | string | Yes      | Genie UUID  |

**Response**

```json theme={null}
{ "success": true }
```

***

### `test`

Sends a test POST request to the webhook URL with a dummy escalation payload. Validates that the endpoint is reachable and returns the HTTP status and response body. Requires the webhook to be active.

**Parameters**

| Field     | Type   | Required | Description |
| --------- | ------ | -------- | ----------- |
| `agentId` | string | Yes      | Genie UUID  |

**Response**

```json theme={null}
{
  "payload": { /* test payload that was sent */ },
  "signature": "abc123...",
  "signatureHeader": "X-HelpGenie-Signature",
  "signed": true,
  "result": {
    "status": 200,
    "body": "ok"
  }
}
```

If the request fails at the network level, `result` will contain an `error` string instead of `status`/`body`.

***

## Error codes

| Code               | Meaning                                    |
| ------------------ | ------------------------------------------ |
| `VALIDATION_ERROR` | Missing required parameter                 |
| `NOT_FOUND`        | No active webhook found (test action only) |
| `UNAUTHORIZED`     | You do not have access to this Genie       |
| `INTERNAL_ERROR`   | Unexpected server error                    |