Webhook Setup Guide

Configuring webhooks lets you deliver call status changes, error events, and other notifications to external systems (Slack / Microsoft Teams / Email / a custom HTTPS endpoint) in real time.

Quickstart

To verify connectivity in the shortest possible path, follow these three steps.

1. Minimal Node.js receiver

import express from 'express';

const app = express();
app.use(express.json());

app.post('/webhook', (req, res) => {
  const { eventType, body } = req.body;

  // Error detection is based on `body.errors`, NOT `body.data.callStatus`.
  if (Array.isArray(body.errors) && body.errors.length > 0) {
    console.error(`[${eventType}] callId=${body.data.callId} has errors`);
  } else {
    console.log(`[${eventType}] callId=${body.data.callId}`);
  }

  // You must return 2xx. Otherwise the delivery is retried with exponential backoff.
  res.sendStatus(200);
});

app.listen(3000);

2. Register the endpoint in the dashboard

In the Recho dashboard's Webhooks page, register the URL above as a Custom endpoint.

3. Enable the triggers

In the Notification Triggers section, pick the events (e.g. OUTBOUND_CALL_ERROR) you want to receive.

That's the minimal setup you need to verify connectivity. Continue reading below for full production setup.

Full setup flow

1. Register a destination endpoint. In the dashboard's Webhook page, choose Create new under Destination Endpoints and pick an endpoint type (Slack / Teams / Email / Custom) and the destination URL or email address.

2. Pick an authentication method (Custom only). Custom endpoints support Bearer token authentication or RSA signature verification. See Authentication for details.

3. Enable the triggers. In the Notification Triggers section, choose which events (e.g. outbound call completed, error, inbound call established) should fire a webhook.

4. Implement your receiver. See the Payload Spec for the payload structure and the Sample Receivers page for reference implementations.

5. Verify and operate. Place a real call or fire a test event to confirm connectivity.

Supported endpoint types

Kind	Notes
Slack	Supply an Incoming Webhook URL; the formatted message is posted to the Slack channel.
Microsoft Teams	Supply a Workflows / Incoming Webhook URL; the message is posted to the Teams channel as an Adaptive Card.
Email	Supply a destination email address; the formatted body is delivered by email.
Custom	Any HTTPS endpoint. JSON is POSTed; supports authentication (Bearer / RSA signature). The most flexible integration option.

Delivery behavior

• Asynchronous delivery: Deliveries run independently of the originating API request. Webhook failures never affect the API response.
• Per-call FIFO ordering: Events for the same callId are delivered in the order they were emitted (FIFO). A FIFO queue is used internally, so a call's state transitions (e.g. OUTBOUND_CALL_CALLING → OUTBOUND_CALL_COMPLETED) will never arrive reversed. Ordering across different calls is not guaranteed.
• Automatic retries on failure: A receiver that returns 408, 429, 5xx, or times out is retried up to 6 times with exponential backoff. See Retry Policy for full details.