Webhook

When an alert procedure ends on CallOnAlarm, the system can automatically send a complete JSON report to a URL of your choice. This allows you to integrate CallOnAlarm with any external system: home automation, ticketing, logging, Slack, custom dashboards, and more.

Availability: Webhooks are available on Pro, Business, and Custom plans only.

---

How It Works

The webhook fires once, at the end of the alert procedure — not during intermediate steps. It sends a complete snapshot of everything that happened: the alert, the contacts called, the call sequence, and the final result.

When does the webhook fire?

Final Status	Description
acknowledged	A contact acknowledged the call
timeout	All contacts were called, none acknowledged
failed	Processing error (no credits, inactive connection…)
cancelled_during_calls	Alert cancelled by a disarm code while calls were in progress
ignored	Event code not configured to trigger calls
technical_only	Only a technical email was sent (no calls)
logged_inactive	Connection was inactive — event logged but no action taken

When does the webhook NOT fire?

• If no webhook URL is configured on the connection

• If the connection's plan is Starter

• During the procedure (no intermediate notifications)

---

Configuration

Setting the Webhook URL

1

Go to Connections and click Manage on your connection.

2

Scroll down to Advanced Settings.

3

Enter your webhook URL in the Webhook URL field.

4

Click Save.

Removing the Webhook URL

Click Remove (or clear the webhook URL field in Advanced Settings and click Save.)

Validation Rules

Rule	Detail
Protocol	Must be http:// or (strongly recommended) https://
Max length	2048 characters
Plan required	Pro, Business, or Custom

---

Payload Reference

HTTP Request

Property	Value
Method	POST
Content-Type	application/json
User-Agent	CallOnAlarm-Webhook/1.0

JSON Structure

The payload is a complete snapshot of the alert procedure. Here is a real-world example where a server went down, a contact was called after the 30-second delay, and acknowledged the alert:

example-payload.json

{
  "alert": {
    "id": "aa7d4ea1-542c-4dc6-9dbd-33ef6aff1e04",
    "event_code": "SRV_DOWN",
    "event_message": "Alert type: Production server unreachable - intervention required.",
    "received_at": "2026-02-04T20:14:06.583Z",
    "raw_message": "API: SRV_DOWN"
  },
  "connection": {
    "id": "1148d514-0e2b-4e94-b05c-ee8c28bacdd1",
    "name": "Connection Business",
    "account_number": "zT14g3HZ",
    "plan": "business",
    "custom_message": null,
    "voice_prefix": "This is an alert from IT Monitoring Corps.",
    "technical_email": "[email protected]",
    "is_active": true
  },
  "client": {
    "id": "c4c8d755-a538-49b1-b1d9-d2e5433529fc",
    "email": "[email protected]",
    "company_name": "CompanyTEST",
    "language": "en"
  },
  "contacts_snapshot": [
    {
      "id": "a92ff1dd-a9bb-45db-9367-f86746d550e6",
      "name": "John Doe",
      "phone": "[phone]",
      "priority": 1,
      "is_active": true
    }
  ],
  "delay_rule_snapshot": {
    "id": "099f6d48-c479-4043-b278-c07220b9f94c",
    "name": "IT RACK54 Server Supervisory",
    "settings": {
      "delay_seconds": 30,
      "technical_codes": ["SRV_UP", "SRV_DOWN"],
      "cancel_call_codes": ["SRV_UP"],
      "trigger_call_codes": ["SRV_DOWN"],
      "custom_event_mapping": {
        "SRV_UP": "Server restored.",
        "SRV_DOWN": "Production server unreachable - intervention required"
      },
      "immediate_call_codes": ["PA"]
    }
  },
  "processing": {
    "initial_status": "calling",
    "final_status": "acknowledged",
    "technical_email_sent": true
  },
  "calls_sequence": [
    {
      "contact_id": "a92ff1dd-a9bb-45db-9367-f86746d550e6",
      "contact_name": "John Doe",
      "phone": "[phone]",
      "priority": 1,
      "call_sid": "CA306a08f481e116f81d7750dc3bf9378e",
      "initiated_at": "2026-02-04T20:14:36.711Z",
      "started_at": "2026-02-04T20:14:36.711Z",
      "ended_at": "2026-02-04T20:14:56.249Z",
      "duration_seconds": 18,
      "status": "completed",
      "acknowledged": true,
      "acknowledged_at": "2026-02-04T20:14:52.598Z"
    }
  ],
  "result": {
    "final_status": "acknowledged",
    "acknowledged": true,
    "acknowledged_by_contact_id": "a92ff1dd-a9bb-45db-9367-f86746d550e6",
    "acknowledged_by_name": "John Doe",
    "acknowledged_by_phone": "[phone]",
    "acknowledged_at": "2026-02-04T20:14:52.598Z",
    "total_calls_made": 1,
    "credits_consumed": 2,
    "total_duration_seconds": 18,
    "response_time_seconds": 46
  }
}

Payload Sections

alert

The original alarm event received.

Field	Type	Description
id	UUID	Unique alert identifier
event_code	string	SIA code (e.g., BA, FA) or custom code (e.g., SRV_DOWN)
event_message	string	Human-readable description of the event
received_at	ISO 8601	When the alert was received
raw_message	string	Original raw message from the panel or API

connection

Snapshot of the connection configuration at the time of the alert.

Field	Type	Description
id	UUID	Connection unique identifier
name	string	Connection name
account_number	string	Account number (can be used to verify the sender)
plan	string	Subscription plan (pro, business, custom)
custom_message	string / null	Custom voice message override (if configured)
voice_prefix	string / null	Custom voice prefix (Business/Custom only)
technical_email	string / null	Technical notification email (if configured)
is_active	boolean	Connection status

client

The account owner.

Field	Type	Description
id	UUID	Client unique identifier
email	string	Client email address
company_name	string / null	Company name (if provided)
language	string	Preferred language (en, fr, es, de…)

contacts_snapshot

All contacts configured at the time of the alert (not just those who were called).

Field	Type	Description
id	UUID	Contact unique identifier
name	string	Contact name
phone	string	Phone number (E.164 format)
priority	number	Call order (1 = first called)
is_active	boolean	Whether this contact was active

delay_rule_snapshot

The delay rule applied to this alert.

Field	Type	Description
id	UUID	Rule identifier
name	string	Rule name
settings	object	Full rule configuration (delay, trigger codes, cancel codes, custom event mapping…)

processing

How the alert was processed by the system.

Field	Type	Description
initial_status	string	Status when processing started
final_status	string	Final outcome (see status table above)
technical_email_sent	boolean	Whether a technical email was sent
cancelled_by_code	string / null	Event code that cancelled the alert (e.g., SRV_UP)

calls_sequence

Ordered list of all phone calls made during the alert. Empty array if no calls were made (e.g., cancelled before calls started).

Field	Type	Description
contact_id	UUID	Contact unique identifier
contact_name	string	Contact who was called
phone	string	Phone number called
priority	number	Priority order
call_sid	string	Unique call reference
initiated_at	ISO 8601	When the call was initiated
started_at	ISO 8601	When the call was answered
ended_at	ISO 8601	When the call ended
duration_seconds	number	Call duration in seconds
status	string	Call status (completed, no-answer, busy, failed)
acknowledged	boolean	Whether this contact acknowledged the alert
acknowledged_at	ISO 8601 / null	When acknowledgment was received

result

Summary of the alert outcome.

Field	Type	Description
final_status	string	Final status of the procedure
acknowledged	boolean	true if someone acknowledged
acknowledged_by_contact_id	UUID / null	ID of the contact who acknowledged
acknowledged_by_name	string / null	Name of the contact who acknowledged
acknowledged_by_phone	string / null	Phone number of the acknowledger
acknowledged_at	ISO 8601 / null	When acknowledgment occurred
total_calls_made	number	Total calls attempted
credits_consumed	number	Credits consumed (2 per call)
total_duration_seconds	number / null	Sum of all call durations
response_time_seconds	number / null	Seconds between alert reception and acknowledgment

---

Delivery & Reliability

Property	Value
Timeout	3 seconds
Retries	None
Model	Fire-and-forget (does not block alert processing)

Your endpoint must respond within 3 seconds with any HTTP 2xx status code. The response body is ignored.

Failure Scenarios

Scenario	What happens
Server returns 4xx or 5xx	Logged as WEBHOOK_FAILED in your connection events
Server takes longer than 3 seconds	Request aborted, logged as WEBHOOK_FAILED
Server unreachable	Logged as WEBHOOK_FAILED

Note: Failed deliveries are visible in your connection's Recent Alerts section. There is no automatic retry — it is your responsibility to monitor your endpoint.

---

Implementation Examples

Python

from http.server import HTTPServer, BaseHTTPRequestHandler
import json

class WebhookHandler(BaseHTTPRequestHandler):
    def do_POST(self):
        body = self.rfile.read(int(self.headers['Content-Length']))
        data = json.loads(body)

        print(json.dumps(data, indent=2))

        self.send_response(200)
        self.end_headers()
        self.wfile.write(b'OK')

HTTPServer(("", 9876), WebhookHandler).serve_forever()

Node.js / Express

const express = require('express');
const app = express();

app.use(express.json());

app.post('/webhook', (req, res) => {
  console.log(JSON.stringify(req.body, null, 2));
  res.sendStatus(200);
});

app.listen(9876, () => console.log('Webhook receiver on :9876'));

Recommendations

• Respond quickly — Your endpoint has 3 seconds. Do heavy processing asynchronously after returning HTTP 200.

• Be idempotent — Use alert.id as a deduplication key.

• Log the raw payload — In case of issues, having the full JSON is invaluable.

• Use HTTPS in production — HTTP is accepted, but HTTPS is strongly recommended.

• Verify the sender — Check that connection.account_number matches your known account number.

---

Use Cases

Integration	Description
Home Automation	Forward alerts to Home Assistant, Jeedom, or Domoticz to trigger automations (lights, locks, camera recording)
Slack / Teams	Post formatted alert messages to a channel with status and acknowledgment details
Custom Dashboard	Ingest webhooks to track alert history, response times, and team performance
Ticketing Systems	Auto-create tickets in Jira, Zendesk, or ServiceNow when result.acknowledged is false
Data Analytics	Forward to Elasticsearch, BigQuery, etc. for long-term analysis of alarm patterns

---

FAQ

Does the webhook fire during the call sequence?

No. The webhook fires once, at the end of the procedure. For real-time monitoring, use the API endpoint GET /v1/alert/:id/status.

Can I receive webhooks for specific event types only?

No. The webhook fires for every alert that reaches a final status. Filter events on your side using alert.event_code or processing.final_status.

Does the webhook consume credits?

No. Webhooks are included in Pro, Business, and Custom plans at no additional cost.

What happens if my server is down?

Failed webhooks are not retried and not queued. You'll see WEBHOOK_FAILED events in your dashboard. The complete alert data is always available in your Dashboard.

Can I test my webhook without triggering a real alarm?

We recommend triggering a real test alert to ensure the entire chain works correctly (alarm → processing → call → webhook). This is the only way to verify that your endpoint receives the payload as expected.

What is the maximum payload size?

A typical payload is around 2.5 KB. In most cases, it should not exceed 8 KB, even with multiple contacts and call rounds. Larger payloads may occur in very rare edge cases.

---

Related

→ Public API Reference → Custom Event Mapping