Skip to content

Message Webhooks

You can receive real-time information about your Enfonica Cloud SMS usage using webhooks. Webhooks are sent using HTTP(S) POST and can be configured to send when:

  • an incoming SMS is received on an SMS-enabled phone number
  • the delivery status of an outgoing SMS changes

Specification

Request

The body of the webhook request is a JSON serialized object.

The request will have header Content-Type: application/json; charset=utf-8.

The request will have header X-Enfonica-Event which specifies which event occurred.

Security

To verify the authenticity of requests to your endpoint, Enfonica includes the header X-Enfonica-Signature. You can use the value of this header to verify that requests are originated by Enfonica.

To calculate the signature:

  1. Get the full original URL of the request, including query parameters.
  2. Append the value of the header X-Enfonica-Event.
  3. Append the JSON payload (original request body).
  4. Sign the resulting string with HMAC-SHA256 using your Enfonica signing key as the key.
  5. Base64 encode the resulting hash code byte array.
  6. Compare the hash to the value of X-Enfonica-Signature. If it matches, then the requests genuinely came from Enfonica.

Response

Some events expect a response body. This is specified against each event below.

If a 2xx response is received, it is deemed that the request was handled successfully. If a redirect is received, it will be followed. Otherwise, it will be deemed that a failure has occurred and attempt:

  • another handler URL if multiple have been specified
  • retry a handler URL that has already been tried

When all handler URLs have been attempted and failed, an additional 8 attempts will be made with delays of 1, 2, 4, 8, 60, 1800, 3600 and 7200 seconds. If all of these attempts fail, no additional attempts will be made.

Incoming message

Incoming message webhooks are sent when an incoming SMS is received on an SMS-enabled phone number.

Enabling this webhook using Enfonica Console

To enable the webhook using the Enfonica Console, specify the target URL against an SMS-enabled phone number instance.

Enabling this webhook using the API

To enable the webhook for an SMS-enabled phone number, specify the target URL against the incoming_message_handler_uris field of the phone number instance.

To enable the webhook for replies to a specific outgoing SMS, specify reply_url when sending the outgoing SMS.

Specification

When an incoming message is received, Enfonica sends a webhook to the URL specified against either:

  • the phone number the message was received on; or, if set
  • the reply_url set on the most recent message between the two parties.

The request will have X-Enfonica-Event: INCOMING_MESSAGE.

The payload of the request will be a JSON serialized instance of the received message. For example:

{
  "name": "projects/example/messages/oprrgs28k9dm5ylgcsqywrrt09j6bg",
  "to": "+61491570006",
  "from": "+61491579212",
  "body": "Hi, this is a test",
  "direction": "INCOMING",
  "segmentCount": 1,
  "price": {
    "units": 0,
    "nanos": 0,
    "currencyCode": "AUD"
  },
  "status": "RECEIVED",
  "createTime": "2021-11-16T23:08:33.813264900Z",
  "encoding": "GSM7"
}

A MessageML response is expected. Alternatively, you can return 204 No Content to indicate the webhook was processed successfully and nothing further should be done.

Message status update

Message status update webhooks are sent when the delivery status of an outgoing SMS is updated.

Enabling this webhook using the API

To enable the webhook for a specific outgoing SMS, specify status_update_url when sending the outgoing SMS.

Specification

When a message status changes to SENT, DELIVERED, UNDELIVERED or FAILED, Enfonica sends a webhook to the URL specified against the message in the status_update_url field.

The request will have X-Enfonica-Event: MESSAGE_STATUS_UPDATE.

The payload of the request will be a JSON serialized instance of the updated message. For example:

{
  "name": "projects/example/messages/5kdls7d50pnhpvt4ug9tshbnmfh38f",
  "to": "+61491579212",
  "from": "+61491570006",
  "body": "Sorry that we missed your call. Reply 1 to receive a callback.",
  "validityPeriodSeconds": 432000,
  "direction": "OUTGOING",
  "segmentCount": 1,
  "price": {
    "currencyCode": "AUD",
    "units": 0,
    "nanos": 55000000
  },
  "status": "DELIVERED",
  "createTime": "2021-11-16T23:31:56.724983Z",
  "sendTime": "2021-11-16T23:31:56.752067Z",
  "deliverTime": "2021-11-16T23:31:59.454562100Z",
  "encoding": "GSM7"
}

No response body is expected.