Callbacks (Webhook)

Callbacks are HTTP POST webhooks Routee sends to your URL when a Failover flow completes a step or reaches a terminal outcome. They apply to Standard and Transactional Failover (POST /failover and POST /failover/transactional).

Failover OTP uses a separate service. OTP webhooks use optional callback.url on create and a different payload shape — see Send a Failover OTP message.

Enable callbacks on create

Include a callback object when you create a flow:

{
  "flow": [ ... ],
  "callback": {
    "strategy": "OnStep",
    "url": "https://your-server.com/failover-webhook"
  }
}

Both strategies use the same JSON payload shape (below). They differ only in when Routee sends it.

When callbacks are sent

The Failover service publishes a callback task when:

1. A step completes and failover advances to the next channel (FlowStepChangedEvent), or
2. The flow reaches a terminal outcome — Succeeded or Failed (FlowStatusChangedEvent).

What is in messages[]: Only completed steps at the time of the callback. The service loads tracking from Routee for each completed step and sorts messages by order, then by type (SMS parts by part, etc.). Steps still in progress are not included until they complete.

If Routee tracking cannot be loaded for a step, a minimal message object is still sent (ids, to, order, failoverOnStatuses, and type) so your webhook is not empty.

HTTP delivery

Example payload (Standard — Viber then SMS)

{
  "trackingId": "30830fad-21ed-49b0-89d0-bbada2fd5640",
  "flowKind": "standard",
  "messages": [
    {
      "type": "Viber",
      "trackingId": "0a047b46-a4dd-4ca8-b817-a6a134dd1234",
      "to": "+306912345678",
      "from": "Routeetest",
      "country": "GR",
      "ttl": 10,
      "expireOnDelivery": false,
      "expiredOnDeliveryAt": null,
      "status": {
        "name": "DELIVERED",
        "reason": {
          "detailedStatus": "Delivered",
          "description": "The message was delivered to its recipient."
        },
        "updatedDate": "2019-07-05T10:28:44.996Z"
      },
      "body": {
        "text": "This is a test, please ignore!",
        "imageUrl": "https://example.com/image.png",
        "action": {
          "caption": "Go",
          "targetUrl": "https://www.routee.net/"
        }
      },
      "label": "labelName",
      "failoverOnStatuses": ["EXPIRED", "FAILED", "UNDELIVERED"],
      "order": 1,
      "inboundUrl": "https://your-server.com/inbound",
      "price": 0.035,
      "createdAt": "2019-07-05T10:28:44.566Z"
    },
    {
      "type": "Sms",
      "messageId": "82a91dc3-e842-41eb-86e5-07d55eb51234",
      "smsId": "1274d238-38b7-4c56-b49a-9b70d25c1234",
      "to": "+306912345678",
      "from": "Routee",
      "country": "GR",
      "operator": "Vodafone",
      "ttl": 15,
      "status": {
        "name": "Delivered",
        "reason": {
          "detailedStatus": "Delivered",
          "description": "The SMS was sent and it was delivered to its recipient."
        },
        "updatedDate": "2019-07-05T10:28:49Z"
      },
      "body": "Hello from failover",
      "price": 0.036,
      "label": "labelName",
      "order": 2,
      "part": 1,
      "parts": 1,
      "latency": 4,
      "failoverOnStatuses": ["Undelivered", "Failed"],
      "createdAt": "2019-07-05T10:28:45.227Z"
    }
  ],
  "terminationChannel": "Sms",
  "status": "Succeeded",
  "statusCode": null,
  "totalPrice": 0.071,
  "originatingService": "failover",
  "applicationId": "5b223c27e4b04b9cdaa71234",
  "createdAt": "2019-07-05T10:28:44.44Z",
  "updatedAt": "2019-07-05T10:28:49.634Z"
}

Notes on the example

• Root status in callbacks is InProgress, Succeeded, or Failed — not Queued (callbacks fire after the flow has started processing).
• originatingService is always the lowercase string failover.
• statusCode is present only when root status is Failed — values "0"–"3" (see Failover Statuses).
• Each message includes type: Sms, Viber, or Voice.
• Viber: body.action (not viberAction); ttl is in minutes (converted from seconds in tracking). Optional body.viberFile, body.viberVideo for rich content.
• SMS: body is a string. Multipart SMS may produce multiple messages[] entries with the same order and different part / smsId.
• Transactional flows (flowKind: transactional): Viber entries use templateId, templateLang, templateParams, deliveryScope, seq instead of promotional body.text / media.

Payload reference — root level

Payload reference — all message types

Viber only

SMS only

Voice only

Callback strategy (summary)

Callback retry policy

Your endpoint must respond with HTTP 200 OK within the callbacks platform HTTP timeout (typically 2 seconds). Otherwise Routee closes the connection and retries delivery via the shared callbacks service.

Documented retry schedule (up to 12 retries over 24 hours):

After retries are exhausted, delivery stops for that callback chain. Design your handler to be idempotent — the same flow update may be POSTed more than once.

Related documentation