Status Update Webhook

Called when the call status changes to track the call lifecycle in your systems.

Called when the call status changes. Use this to track call lifecycle in your systems.

When It's Called

The webhook is triggered when the call status changes to:

in-progress - Call connected, conversation started
ended - Call ended normally (customer hung up)
ended-with-error - Call ended due to an error

Request Payload

Call Started (in-progress)

{
  "message": {
    "type": "status-update",
    "timestamp": "2025-12-13T12:00:00.000Z",
    "call": {
      "id": "5c4d030f-43e3-4e65-899e-8148521e660f",
      "type": "inbound_phone_call",
      "status": "in-progress"
    },
    "phone_number": {
      "number": "+31850835037",
      "name": "HMS Sovereign Demo"
    },
    "customer": {
      "number": "+31612345678"
    }
  }
}

Call Ended Normally

{
  "message": {
    "type": "status-update",
    "timestamp": "2025-12-13T12:05:00.000Z",
    "call": {
      "id": "5c4d030f-43e3-4e65-899e-8148521e660f",
      "type": "inbound_phone_call",
      "status": "ended"
    },
    "phone_number": {
      "number": "+31850835037",
      "name": "HMS Sovereign Demo"
    },
    "customer": {
      "number": "+31612345678"
    }
  }
}

Call Ended with Error

{
  "message": {
    "type": "status-update",
    "timestamp": "2025-12-13T12:05:00.000Z",
    "call": {
      "id": "5c4d030f-43e3-4e65-899e-8148521e660f",
      "type": "inbound_phone_call",
      "status": "ended-with-error"
    },
    "phone_number": {
      "number": "+31850835037",
      "name": "HMS Sovereign Demo"
    },
    "customer": {
      "number": "+31612345678"
    },
    "error": "STT connection failed"
  }
}

Response

The response body is ignored. Return any 2xx status code to acknowledge receipt.

HTTP/1.1 200 OK

Use Cases

Update CRM with call activity
Track active calls in real-time dashboard
Alert on call errors
Log call events for analytics

Example Implementation (Node.js)

app.post('/webhooks/status-update', async (req, res) => {
  const { message } = req.body;
  
  // Update CRM
  await crm.logActivity({
    type: 'call',
    phone: message.customer.number,
    status: message.call.status,
    timestamp: message.timestamp
  });
  
  // Track active calls
  if (message.call.status === 'in-progress') {
    await redis.sadd('active_calls', message.call.id);
  } else {
    await redis.srem('active_calls', message.call.id);
  }
  
  // Alert on errors
  if (message.call.status === 'ended-with-error') {
    await slack.send({
      channel: '#alerts',
      text: `Call error: ${message.error}`
    });
  }
  
  res.status(200).send('OK');
});

See Status Update Webhook API for complete schema details.

On this page