Webhooks

Webhooks let Atlas push events to your systems the moment they happen — when a call starts or ends, or when a chat message is received or sent. Instead of polling the API, you register a URL once and Atlas sends an HTTP POST to it every time the event fires.

This is the inverse of Atlas Actions: Actions let your agent call out to your API during a conversation, while webhooks let Atlas notify your API after something happens.

How it works

1. You register a webhook for a campaign and an event (a trigger).
2. When that event fires, Atlas sends a POST request to your URL with the event payload as JSON.
3. Your endpoint responds quickly with a 2xx status code.

All requests use the standard API base URL and api-key authentication — see API Overview.

https://api.youratlas.com/v1/api

Events

You can subscribe to four events. The triggerName value is what you pass when subscribing.

Subscribe (create a webhook)

Register a webhook by POSTing to /events-gateway/trigger/subscribe.

$
curl --location 'https://api.youratlas.com/v1/api/events-gateway/trigger/subscribe' \
>
  --header 'api-key: YOUR_API_KEY' \
>
  --header 'Content-Type: application/json' \
>
  --data '{
>
    "hookUrl": "https://example.com/atlas/webhook",
>
    "campaignId": "76effd5c-7286-4d3c-9f8e-e5d4c8287d12",
>
    "triggerName": "call_completed",
>
    "provider": "custom"
>
  }'

A successful subscription returns 201:

1
{
2
  "id": "https://example.com/atlas/webhook",
3
  "campaignId": "76effd5c-7286-4d3c-9f8e-e5d4c8287d12",
4
  "triggerName": "call_completed"
5
}

Event payloads

When an event fires, Atlas sends a POST to your hookUrl with Content-Type: application/json. The body is a JSON array containing the event object.

call_started

1
[
2
  {
3
    "campaignId": "string",
4
    "agentId": "string",
5
    "callId": "string",
6
    "customerNumber": "string",
7
    "customerName": "string",
8
    "campaignName": "string",
9
    "agentName": "string",
10
    "campaignType": "string"
11
  }
12
]

call_completed

Includes everything from call_started, plus the call result:

1
[
2
  {
3
    "campaignId": "string",
4
    "agentId": "string",
5
    "callId": "string",
6
    "customerNumber": "string",
7
    "customerName": "string",
8
    "campaignName": "string",
9
    "agentName": "string",
10
    "campaignType": "string",
11
    "callSummary": "string",
12
    "startedAt": "2026-06-02T13:04:30.000Z",
13
    "endedAt": "2026-06-02T13:08:11.000Z",
14
    "durationMs": 221000,
15
    "durationSeconds": 221,
16
    "durationMinutes": 3.68,
17
    "callTranscript": "string",
18
    "audioUrl": "https://...",
19
    "customerEmail": "string",
20
    "status": "Accepted",
21
    "endedReason": "customer-ended-call"
22
  }
23
]

message_received / message_sent

1
[
2
  {
3
    "campaignId": "string",
4
    "agentId": "string",
5
    "customerNumber": "string",
6
    "customerName": "string",
7
    "campaignName": "string",
8
    "agentName": "string",
9
    "campaignType": "string",
10
    "messageContent": "string",
11
    "receivedAt": "2026-06-02T13:04:30.000Z"
12
  }
13
]

message_sent uses sentAt instead of receivedAt.

$
curl --location 'https://api.youratlas.com/v1/api/events-gateway/trigger/perform/call_completed?campaignId=YOUR_CAMPAIGN_ID' \
>
  --header 'api-key: YOUR_API_KEY'

List webhooks

See every webhook registered for a campaign:

$
curl --location 'https://api.youratlas.com/v1/api/events-gateway/triggers/campaign/YOUR_CAMPAIGN_ID' \
>
  --header 'api-key: YOUR_API_KEY'

Unsubscribe (delete a webhook)

Stop delivery by sending a DELETE to /events-gateway/trigger/unsubscribe with the same values you subscribed with:

$
curl --location --request DELETE 'https://api.youratlas.com/v1/api/events-gateway/trigger/unsubscribe' \
>
  --header 'api-key: YOUR_API_KEY' \
>
  --header 'Content-Type: application/json' \
>
  --data '{
>
    "hookUrl": "https://example.com/atlas/webhook",
>
    "campaignId": "76effd5c-7286-4d3c-9f8e-e5d4c8287d12",
>
    "triggerName": "call_completed",
>
    "provider": "custom"
>
  }'

Building your receiver

• Respond with 2xx quickly. Acknowledge the request and do any heavy processing asynchronously. Slow endpoints may time out.
• Expect retries to be best-effort. If your endpoint is unreachable, the event may not be redelivered — don’t rely on a webhook as your only record of an event; the Calls and chat endpoints remain the source of truth.
• Handle duplicates. Treat delivery as at-least-once and de-duplicate on callId (calls) or message identifiers where it matters.