Skip to main content
Receive real-time notifications when events occur in any sub-account. Configure webhook URLs at the partner level.

​
Configure Webhooks

POST /webhooks
​
url
string
required
Your webhook endpoint URL (must be HTTPS)
​
events
array
required
Array of event types to subscribe to
​
secret
string
required
Secret for HMAC signature verification
curl -X POST https://api.recoverbiz.com/v1/webhooks \
  -H "X-Partner-Key: pk_live_abc123def456..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://yourplatform.com/webhooks/recover",
    "events": [
      "conversation.started",
      "conversation.reply_received",
      "conversation.handoff_requested",
      "lead.status_changed",
      "lead.created",
      "checklist.item_collected",
      "checklist.completed",
      "sequence.completed",
      "sequence.reply_received"
    ],
    "secret": "whsec_your_signing_secret"
  }'
Response: 201 Created 
{
  "id": "wh_001",
  "url": "https://yourplatform.com/webhooks/recover",
  "events": [
    "conversation.started",
    "conversation.reply_received",
    "conversation.handoff_requested",
    "lead.status_changed",
    "lead.created",
    "checklist.item_collected",
    "checklist.completed",
    "sequence.completed",
    "sequence.reply_received"
  ],
  "active": true,
  "created_at": "2026-02-15T10:30:00Z"
}

​
Event Types

EventFires When
conversation.startedFirst message exchanged with a new lead
conversation.reply_receivedLead sends an inbound message
conversation.handoff_requestedAI flags conversation for human review
lead.status_changedLead status transitions (new -> contacted, etc.)
lead.createdNew lead imported via API or conversation
checklist.item_collectedA document or data point is collected
checklist.completedAll required checklist items are collected
sequence.completedA lead finishes all sequence steps
sequence.reply_receivedLead replies during an active sequence

​
Webhook Payload

All webhooks include a consistent envelope: 
{
  "id": "evt_abc123",
  "type": "checklist.completed",
  "account_id": "acc_8f3a1b2c",
  "created_at": "2026-02-14T15:30:00Z",
  "data": {
    "phone": "+14155551234",
    "lead_name": "John Doe",
    "checklist_progress": 1.0,
    "completed_items": 4,
    "total_items": 4
  }
}

​
Example Payloads

{
  "id": "evt_def456",
  "type": "conversation.reply_received",
  "account_id": "acc_8f3a1b2c",
  "created_at": "2026-02-14T15:30:00Z",
  "data": {
    "phone": "+14155551234",
    "lead_name": "John Doe",
    "message_body": "Sure, I can send the bank statements tomorrow.",
    "message_direction": "inbound"
  }
}

{
  "id": "evt_ghi789",
  "type": "lead.status_changed",
  "account_id": "acc_8f3a1b2c",
  "created_at": "2026-02-14T16:00:00Z",
  "data": {
    "phone": "+14155551234",
    "lead_name": "John Doe",
    "previous_status": "new",
    "new_status": "contacted"
  }
}

{
  "id": "evt_jkl012",
  "type": "conversation.handoff_requested",
  "account_id": "acc_8f3a1b2c",
  "created_at": "2026-02-14T17:00:00Z",
  "data": {
    "phone": "+14155551234",
    "lead_name": "John Doe",
    "reason": "Lead requested to speak with a human agent"
  }
}

​
Signature Verification

Every webhook includes an X-Recover-Signature header containing an HMAC-SHA256 signature of the raw request body using your webhook secret. 
const crypto = require('crypto');

function verifyWebhook(body, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(body)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

// In your Express handler (use express.raw() to get the raw body):
app.post('/webhooks/recover', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.headers['x-recover-signature'];
  const isValid = verifyWebhook(req.body, signature, WEBHOOK_SECRET);

  if (!isValid) {
    return res.status(401).send('Invalid signature');
  }

  const event = JSON.parse(req.body);
  const { type, data, account_id } = event;
  // Handle the event...

  res.status(200).send('OK');
});
Always verify the webhook signature before processing the event. Never trust the payload without verification.

​
Delivery & Retries

Recover delivers webhooks with automatic retry on failure:
AttemptDelay
1st retry30 seconds
2nd retry2 minutes
3rd retry10 minutes
4th retry1 hour
5th retry4 hours
Your endpoint must respond with a 2xx status within 10 seconds or the delivery is considered failed. After 5 failed retries, the event is dropped and a webhook.delivery_failed event is logged in your partner dashboard.
Each webhook delivery includes an X-Recover-Delivery-Id header with a unique delivery ID for idempotency tracking.

​
List Webhooks

GET /webhooks Returns all configured webhook endpoints. 
curl https://api.recoverbiz.com/v1/webhooks \
  -H "X-Partner-Key: pk_live_abc123def456..."
Response: 200 OK 
{
  "webhooks": [
    {
      "id": "wh_001",
      "url": "https://yourplatform.com/webhooks/recover",
      "events": ["conversation.reply_received", "checklist.completed"],
      "active": true,
      "created_at": "2026-02-10T09:00:00Z"
    }
  ]
}

​
Update Webhook

PATCH /webhooks/:webhook_id Update the URL, events, or active status. 
curl -X PATCH https://api.recoverbiz.com/v1/webhooks/wh_001 \
  -H "X-Partner-Key: pk_live_abc123def456..." \
  -H "Content-Type: application/json" \
  -d '{
    "events": ["conversation.reply_received", "checklist.completed", "lead.status_changed"],
    "active": true
  }'

​
Delete Webhook

DELETE /webhooks/:webhook_id 
curl -X DELETE https://api.recoverbiz.com/v1/webhooks/wh_001 \
  -H "X-Partner-Key: pk_live_abc123def456..."
Response: 200 OK 
{
  "success": true,
  "deleted": true
}