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

messageStatus values

In addition to the statusCode, a messageStatus provides additional detail, as described in the table below.

statusCode messageStatus Description
0 1002 Message has been sent
1 999 Message queued without receipt
2 1001 Message queued for delivery
4 1003 Message accepted by Carrier
5 1005 Message rejected
5 1006 Message expired
5 1007 Message failed
5 1008 Permanent Send Error
5 1100 Unknown error
5 1101 Source Carrier Invalid
5 1102 Destination Carrier Invalid
5 1103 Source Not Authorized
5 1104 Source Carrier Disabled
5 1105 Destination Carrier Disabled
5 1106 No Valid Route
5 1107 Invalid Source TON
5 1108 Invalid Destination TON
5 1109 Route Denied
5 1110 User Opted Out (STOP)
5 1111 Temporary Resolution Failure
5 1112 Permanent Resolution Failure
5 1115 No Handler found
5 1116 Destination Address is not text enabled
5 1150 Spam
5 1152 Spam Reject
5 1200 Unknown error
5 1201 Message too long
5 1202 Invalid Priority Flag
5 1204 System error
5 1205 Invalid source address
5 1206 Invalid destination address
5 1207 Message ID is invalid
5 1208 Cancelling message failed
5 1209 Message replacement failed
5 1210 Message queue full
5 1211 Invalid service type
5 1212 Invalid number of destinations
5 1213 Invalid distribution list name
5 1214 Invalid destination flag
5 1215 Invalid submit with replace request
5 1216 Invalid esmeclass set
5 1217 Invalid submit to distribution list
5 1218 Submitting message has failed
5 1219 Invalid source address type of number (TON)
5 1220 Invalid source address numbering plan (NPI)
5 1221 Invalid destination address type of number (TON)
5 1222 Invalid destination address numbering plan (NPI)
5 1223 Invalid replace_if_present flag
5 1224 Invalid number of messages
5 1225 Throttling error
5 1226 Invalid scheduled delivery time
5 1227 Invalid Validity Period value
5 1228 ESME Receiver temporary error
5 1229 ESME Receiver permanent error
5 1230 ESME Receiver reject message error
5 1231 Message query request failed
5 1232 Error in the optional part of the PDU body
5 1233 TLV not allowed
5 1234 Invalid parameter length
5 1235 Expected TLV missing
5 1236 Invalid TLV value
5 1237 Transaction delivery failure
5 1238 Specified servicetype is unavailable
5 1239 Specified servicetype is denied
5 1240 Invalid data coding scheme
5 1241 Invalid source address subunit
5 1242 Invalid destination address subunit
5 1243 Insufficient credits to send message
5 3120 Invalid registered delivery flag
6 1004 Message delivered to handset

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: