Zipwhip Webhooks API

Zipwhip webhooks push real-time server-to-server notifications of incoming and outgoing messages and other state changes occurring in your account. You must provide a public facing url to receive webhook callbacks.

API Specs

Zipwhip Webhook API specs are available in both OpenAPI and Postman format.

Webhook Event Types

You can subscribe to the following Events.

Type Event Description
message receive Alerts when an incoming message is received.
message send Alerts when a message is sent from your number.
message progress Alerts when an outgoing message changes its status.
message read Alerts when an incoming message has been read.
message delete Alerts when one of your messages have been removed from the database.
optout change Alerts when an incoming message contains the keywords “STOP” or “UNSTOP”.

Webhook Payload

The webhook payload is in application/json format. Example payloads appear below.

Message Payload

The message type payload contain properties specific to a message. Each of the message events (receive, send, progress, read,delete) contain similar payloads.

POST /message/receive HTTP/1.1
Content-Type: application/json;charset=UTF-8
Content-Length: 753
User-Agent: Apache-HttpClient/4.5.7 (Java/1.8.0_201)

  "body": "Hello World",
  "bodySize": 11,
  "address": "ptn:/+12063996756",
  "finalSource": "+12063996756",
  "finalDestination": "+12068163958",
  "messageType": "MO",
  "fingerprint": "1514465037",
  "id": 1327295480212647936,
  "cc": null,
  "visible": true,
  "read": false,
  "bcc": null,
  "contactId": 14543967707,
  "scheduledDate": null,
  "deviceId": 377265507,
  "dateDeleted": null,
  "messageTransport": 5,
  "dateDelivered": null,
  "hasAttachment": false,
  "dateCreated": "2020-11-13T17:01:17Z",
  "deleted": false,
  "dateRead": null,
  "statusCode": 4,
  "messageStatus": 1003
Consuming large message body as text attachment

Note: Upon receipt of a message, it is important to look at the hasAttachment field before parsing the body. If hasAttachment is true, there may be a .txt attachment. When present, the contents of the text attachment supersedes what is in the body field. To ensure proper receipt of the message body, you must consume the content of the text file and use that as the body, ignoring what is in the body field itself. The reason for this is because there is a size limitation on the body field. When that limit is exceeded, the entire contents of the text portion of the message will be stored as an attachment.

Optout Payload

The optout payload includes information specific to when a STOP or UNSTOP event occurs.

POST /optout/change HTTP/1.1
Content-Type: application/json;charset=UTF-8
Content-Length: 358
User-Agent: Apache-HttpClient/4.5.7 (Java/1.8.0_201)

  "messageBody": "Stop",
  "line": "+12068163958",
  "contact": "+12063996756",
  "messageId": "1195424825893195776",
  "type": "STOP",
  "eventDate": "2019-11-15T19:34:23+00:00"

Webhook Progress Status Codes

If the message/progress event is registered a message payload will be delivered with an updated statusCode as the message is processed. The message progress status codes are detailed in the table below:

Status Code Description State Final State
0 Successful transmission - no acknowledgment from carrier Success True
1 In Process Transient False
2 Queued Transient False
4 Successful delivery to carrier Success True
5 Failed delivery to carrier Failure True
6 Successful delivery to handset (toll-free numbers only) Success True
7 Failed delivery to handset (toll-free numbers only) Failure True

Webhook Endpoint Failures

If the provided web endpoint responds with a non 200-level code then the message is considered failed. Additionally, if the web server does not respond for 7 seconds then it is considered failed. When a message has failed it is put into a retry queue where it will be resent for 72 hours or until it gets a 200-level response. The failed messages use a exponential back-off algorithm so that every time it fails there is more time before it is sent again.

Webhook Server IP Addresses

If you are using a firewall to restrict webhook callbacks to your server, you may need to add Zipwhip’s webhook server addresses to your allowlist. Zipwhip currently sends webhooks from the following range of IP addresses:

NOTE: As of August 15, 2021, Zipwhip is no longer sending from this range of IP addresses: