Escalation Webhooks

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

{
  "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.

{
  "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

{ "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

{
  "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

Overview

Public (unauthenticated)

Agents

Knowledge

CRM

Marketplace

Platform

Telephony

Worker genies

Quality & Compliance

Access Control

Intelligence

Education

Voice

Integrations

Expanded Platform

Actions

`get`

`upsert`

`delete`

`test`

Error codes

​Actions

​get

​upsert

​delete

​test

​Error codes

Actions

`get`

`upsert`

`delete`

`test`

Error codes