Appendix A: Webhooks

The Lark Router supports advanced webhooks or APIs to expand functionality.  The third-party system will need to be configured to support those APIs. A description provided for each one.

Message Routing using Webhooks #

The routing Webhook is called with an HTTP POST body containing a JSON object. The fields are listed below

Fields

The webhook must return the HTTP 200 code, and a single line of the form:

• destination-bind: e.g. “Client-001” which is the bind through which the message should be sent. For MT this should be the supplier bind ID, for MO, it should be the client bind ID. Alternatively:
• destination-bind-type,destination-bind: e.g. “supplier, Supplier-001” where the first string before the comma is the type of bind (must be set to supplier or carrier), and the string after the comma is the bind ID as above. This form of response makes it possible to, say, route a supplier-originated MO MMS back to a supplier as an MT MMS, by returning the bind-type as the supplier. 

No response or timeout will result in the message being rejected.

Example Request

{"phone-number": "165123456",
"message-type": "mms", "message-subject": "xyz123", "bind-id": "carrier1",
"direction": "MO", 
"message-id": "00001", }

Example Response

supplier,mm7-carrier-bind-1

CDR Webhook #

Overview

The Lark router supports a CDR Webhook to allow Providers to collect, maintain, report, and store events based on their corporate policies. An HTTP POST using JSON is available. This webhook is called when an MT message is delivered, expired or rejected. For MO it is called when the message is forwarded to the VASP.

To configure this, go to

Configuration ->Lark -> Queues, CDR & Caching

Set External CDR API URL to the URL that the Lark router will post the billing event to.

You may also change how long the Lark Router will store the CDRs in the server. The default is 365 days.

Once the message is received (The webhook receives and HTTP 200) the next event will be posted synchronously.

CDR Parameters

Example

{
"cdr-params":{
"message-date":"2019-02-13T10:47:03Z",
"cdr-date":"2019-02-13T10:49:03Z",
"source-bind":"newscorp2",
"destination-bind":"local",
"from":"111",
"to":"222",
"size":4494,
"message-type":"MMS",
"message-priority":"low",
"carrier-message-id":"201902131046411550044001",
"transaction-id":"e55670WZNo",
"delivery-status":"Sent"
},
"message-params":{
"mms-version":"1.0",
"delivery-report":"Yes",
"content-types":[
"application/octet-stream"
]
},
"envelope-params":{
"direction":"MT",
"priority":"0",
"attempts":"2"
}
}

Billing Webhook #

Overview

The Lark router supports a Billing Webhook to assist Providers in billing their clients for message traffic. An HTTP POST using JSON is available.

To configure this, go to

Configuration→Lark → Queues, CDR & Caching

Set External Billing to the URL that the Lark router will post the billing event to.

and

Choose when the billing event should be posted.

• On MMS Submission to the Gateway.

This is the default behavior as all messages counted in licensing totals and will be invoiced to the provider,

• On MMS Submission to the Destination bind.

This would be used when only forwarded messages are to be billed to your customer.

• On MMS Delivery to Destination Phone or VASP (DLR is received)
  Billed upon delivery (Success).

Once the event is received (HTTP 200) the next event will be posted this is a synchronous process.

Field Description

Notes:

• carrier-message-id: The message ID on the carrier side. This will only appear for messages to a carrier
• dlr-status: The delivery status (for a DLR only)
• delivery-status: For messages to a carrier, this will be indicated if the message was accepted for delivery or rejected.

Example:

{
   "cdr-params":{
      "message-date":"2018-10-19T13:59:25Z",
      "cdr-date":"2018-10-19T13:59:40Z",
      "source-bind":"testcorp",
      "destination-bind":"carrier1",
      "from":"222",
      "to":"111",
      "size":70,
      "message-type":"m-send-req",
      "message-priority":"low",
      "carrier-message-id":"dc35a3LtVu",
      "delivery-status":"Retrieved",
      "dlr-status":"Retrieved"
   },
   "message-params":{
      "transaction-Id":"112001",
      "mms-version":"1.0",
      "content-types":"text/plain",
      "delivery-report":"Yes",
      "message-type":"m-send-req"
   },
   "envelope-params":{
      "priority":"0",
      "direction":"MT",
      "message-id":"dc35a3LtVu",
      "attempts":"1"
}