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

The payload depends on your App's API version:

• Legacy: the same Meta-compatible format as pool number webhooks, plus pipes.conversationId. See Webhook Payload.
• API v2: one envelope per Meta change, with Meta's change.value untouched in whatsapp. Statuses and template updates are delivered too. See API v2 envelope, the migration guide and the example payloads.

Signatures

Every delivery to your App webhook URL is signed with Standard Webhooks (webhook-id, webhook-timestamp and webhook-signature headers), using your App's whsec_ signing secret. Reveal or rotate the secret in your App's settings. See Webhook Security for verification code.

webhook-id is identical across retries of the same delivery, so you can use it to deduplicate.

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 signed like every App webhook 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
• BYON API v2 Migration — Move your App to API v2
• Number Management — Monitor your BYON numbers