Webhooks

Subscribe an HTTPS endpoint to events and LimePhone will POST each occurrence to you as it happens — no polling.

Events

Event	Fires when
call.created	A call starts
call.completed	A call ends
call.failed	A call fails
message.sent	An outbound message is sent
message.received	An inbound message arrives
message.failed	A message fails to deliver

Delivery

Deliveries are JSON POSTs with a 10-second timeout. A non-2xx response is retried with backoff up to your subscription's maxRetries (default 3). Each delivery carries:

Header	Meaning
X-Webhook-Event	The event name, e.g. call.completed
X-Webhook-Delivery-Id	Unique id for this delivery (stable across retries)
X-Webhook-Signature	HMAC-SHA256 signature — verify it before trusting the payload

Verifying signatures

Every subscription has a secret, returned when you create it. The signature is HMAC-SHA256(secret) over the string {timestamp}.{deliveryId}.{rawBody}, where timestamp is the timestamp field inside the payload and rawBody is the exact JSON body as received. Compare with a constant-time comparison and reject anything that doesn't match.

// Node.js — capture the raw request body for signing
const crypto = require('crypto');

function verify(req, secret) {
  const payload = JSON.parse(req.rawBody);
  const canonical = payload.timestamp + '.' +
    req.headers['x-webhook-delivery-id'] + '.' + req.rawBody;
  const expected = crypto.createHmac('sha256', secret)
    .update(canonical).digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(req.headers['x-webhook-signature']));
}

# Python — same verification with Flask
import hashlib, hmac, json

def verify(raw_body: bytes, headers, secret: str) -> bool:
    payload = json.loads(raw_body)
    canonical = f"{payload['timestamp']}.{headers['X-Webhook-Delivery-Id']}.{raw_body.decode()}"
    expected = hmac.new(secret.encode(), canonical.encode(), hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, headers.get("X-Webhook-Signature", ""))

A complete receiver

// Node.js / Express — capture the RAW body (signature covers the exact bytes)
const express = require('express');
const crypto = require('crypto');

const app = express();
app.post('/hooks/limephone',
  express.raw({ type: 'application/json' }),
  (req, res) => {
    const raw = req.body.toString('utf8');
    const payload = JSON.parse(raw);
    const canonical = `${payload.timestamp}.${req.headers['x-webhook-delivery-id']}.${raw}`;
    const expected = crypto.createHmac('sha256', process.env.LIMEPHONE_WEBHOOK_SECRET)
      .update(canonical).digest('hex');
    if (!crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(req.headers['x-webhook-signature'] || ''))) {
      return res.status(401).end();
    }
    switch (req.headers['x-webhook-event']) {
      case 'call.completed':
        console.log('Call finished:', payload.data);
        break;
      case 'message.received':
        console.log('Inbound message:', payload.data);
        break;
    }
    res.status(200).end(); // respond fast; do heavy work async
  });
app.listen(3000);

Example event payload

{
  "event": "call.completed",
  "timestamp": "2026-09-04T14:03:22.000Z",
  "data": {
    "id": "call_abc123",
    "direction": "inbound",
    "from": "[phone]",
    "to": "[phone]",
    "status": "completed",
    "duration": 184
  }
}

List webhooks

GET /v1/webhooks — scope webhooks:read

Lists your webhook subscriptions. Also available: GET /v1/webhooks/{id} for one.

Create a webhook

POST /v1/webhooks — scope webhooks:write

Creates a subscription. The response includes the signing secret — store it now; treat it like a password.

Field	Type	Required	Notes
url	string	yes	HTTPS endpoint to receive deliveries
events	string[]	yes	One or more event names from the list above
description	string	no
maxRetries	integer 0–10	no	Retry attempts on failure. Default 3

curl -X POST https://dashboard.limephone.io/api/v1/webhooks \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/hooks/limephone",
    "events": ["call.completed", "message.received"]
  }'

Update a webhook

PATCH /v1/webhooks/{id} — scope webhooks:write

Change the URL or events, pause with isActive: false, or adjust maxRetries.

Delete a webhook

DELETE /v1/webhooks/{id} — scope webhooks:write

Deletes a subscription. Returns 204. Deliveries stop immediately.