Sign in

v1

latestOpenAPI 3.0.12026-07-226992320.0 KB
Webhooks

Create Webhook

Registers a new webhook to receive real-time event notifications on your HTTPS endpoint. The webhook is scoped to a single agent and fires only for the event types you specify. Returns the created webhook including its webhookId and HMAC secret — store the secret securely as it is only returned once.

post/v1/webhooks

Request body

namestring required

Human-readable name for this webhook. Used to identify it in listings and dashboards. Does not need to be unique, but a descriptive name helps distinguish multiple webhooks on the same agent.

agentIdstring required

Unique identifier of the agent this webhook is scoped to. Only events originating from this agent will be delivered to this webhook's URL. Use the agentId returned when the agent was created.

urlstring required

HTTPS endpoint that will receive event payloads as HTTP POST requests. Must be publicly reachable. The system expects an HTTP 2xx response within the configured timeout to confirm delivery. Non-2xx responses or timeouts are treated as delivery failures.

eventsstring[] required

Set of event types that will trigger a delivery to this webhook. 'conversation_started' fires when an agent session begins. 'conversation_ended' fires when a session closes. 'conversation_analysed' fires when post-call analysis is complete. At least one event must be specified. Only events in this set will be sent — all others are silently ignored.

Example request

{
  "name": "Call Events - Production",
  "agentId": "D5D0p7TUs66TTAEAx",
  "url": "https://yourapp.com/webhooks/sigmamind",
  "events": [
    "conversation_started",
    "conversation_ended"
  ]
}

Response

Created

workspaceIdstring

Unique identifier of the workspace this webhook belongs to. Use this value to scope queries or filter webhooks by workspace.

webhookIdstring

Unique identifier for this webhook. Use this value as webhookId when updating, deleting, or retrieving this webhook via the API.

namestring

Display name of this webhook as set at creation time. Used to identify it in listings and dashboards.

agentIdstring

Unique identifier of the agent this webhook is scoped to. Only events originating from this agent are delivered to this webhook's URL.

activeboolean

Whether this webhook is currently active and will receive event deliveries. When false, the webhook is registered but no events are sent to the URL. Toggle this to pause or resume delivery without deleting the webhook.

secretstring

HMAC secret key used to sign outgoing webhook payloads. The system includes a signature header on each delivery computed using this secret. Verify the signature on your server to confirm payloads are genuinely from SigmaMind. Store this value securely — it is only returned at creation time.

eventsstring[]

Event types this webhook is subscribed to. Only events in this list trigger a delivery to the webhook URL. 'conversation_started' fires when an agent session begins. 'conversation_ended' fires when a session closes. 'conversation_analysed' fires when post-call analysis is complete.

urlstring

Example response

{
  "workspaceId": "org_BUbkx3PsbzQm5V10",
  "webhookId": "wh_BUbkx3PsbzQm5V10",
  "name": "Call Events - Production",
  "agentId": "D5D0p7TUs66TTAEAx",
  "active": true,
  "secret": "mK9vXq2pL8nR5tY1wA3sD6fH0jC4bE7u"
}