Skip to main content
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
FieldTypeRequiredDescription
agentIdstringYesGenie 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
FieldTypeRequiredDescription
agentIdstringYesGenie UUID
urlstringYesHTTPS endpoint to POST to on escalation
secretstringNoShared secret used to sign the payload (HMAC-SHA256)
secret_headerstringNoHeader name for the signature, defaults to X-HelpGenie-Signature
custom_fieldsarrayNoCustom 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_activebooleanNoWhether 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
FieldTypeRequiredDescription
agentIdstringYesGenie 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
FieldTypeRequiredDescription
agentIdstringYesGenie 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

CodeMeaning
VALIDATION_ERRORMissing required parameter
NOT_FOUNDNo active webhook found (test action only)
UNAUTHORIZEDYou do not have access to this Genie
INTERNAL_ERRORUnexpected server error