Webhook Delivery

BYON Apps support dual delivery — messages are delivered to both your webhook URL and any connected WebSocket clients in parallel. This ensures maximum reliability.

Configuring a webhook

In your App's settings, set a Webhook URL — an HTTPS endpoint that Pipes.bot will POST messages to.

https://your-app.example.com/webhook/pipes

Messages from any sender on any of your App's BYON numbers will be delivered to this URL.

Delivery behavior

When a message arrives on a BYON number:

1. Webhook: Pipes.bot sends an HTTP POST to your App's webhook URL
2. WebSocket: Simultaneously delivered to any connected WebSocket clients authenticated with your ak_ key

Both deliveries happen in parallel. If one fails, the other still succeeds.

Retry policy

Failed webhook deliveries are retried up to 3 times with a 10-second per-attempt timeout:

After 3 failed attempts the payload is persisted to the WebhookDelivery table with status pending for manual retry. It is not auto-delivered over another channel.

Testing your webhook

Use the Test Webhook button in your App's settings to send a sample payload to your configured URL. This helps verify your endpoint is reachable and processing messages correctly before going live.

Webhook payload

BYON webhook payloads follow the same format as pool number webhooks. See the Webhooks documentation for full payload details, signature verification, and error handling.

The number.onboarded event

When a BYON number finishes Embedded Signup, Pipes.bot POSTs a number.onboarded event to your App's webhook URL. The event is unsigned and retried 3× (0s / 2s / 8s), then persisted to WebhookDelivery on exhaustion.

{
  "event": "number.onboarded",
  "timestamp": "2025-01-15T10:30:00.000Z",
  "data": {
    "numberId": "pn_abc123",
    "phoneNumber": "+15551234567",
    "displayName": "Acme Support",
    "appId": "app_abc123",
    "metadata": { "partnerId": "partner_123" }
  }
}

metadata round-trips whatever you passed to POST /v1/apps/token. Use it to correlate the onboarded number with your internal records.

Next steps

• Webhooks — Full webhook payload reference
• Number Management — Monitor your BYON numbers