Webhooks

Drop Cowboy will notify you via webhook by http POST to the URL you specify in your API request. You will receive JSON content containing the delivery status of every voicemail you attempt to send.

Drop Cowboy will notify you via webhook by http POST to the callback_url you specify in your /sms API request. You will receive JSON content containing the delivery status of every voicemail you attempt to send. Your server should be capable of handling a high number of concurrent requests which will scale up or down based on your sending volume. High volume senders should consider employing a queueing technology such as AWS SQS or RabbitMQ as a buffer in order to handle the potentially high concurrency calls to your callback_url coming from Drop Cowboy.

Linking Webhook Results Back to Your Database

Drop Cowboy sends a webhook response for every /sms request that we receive. You can link the delivery results back to records in your database by passing foreign_id as part of your /sms API request. It is common to pass a database record id that identifies the delivery attempt or other record within your system.

---

Example Webhook (Successful Delivery):

{
    "drop_id": "5c8eb7940a057a4ab0823e1a",
    "phone_number": "[phone]",
    "attempt_date": "2019-03-17T21:10:26.000Z",
    "status": "success",
    "reason": "",
    "dnc": false,
    "spam": false,
    "product_cost": 0.099,
    "compliance_fee": 0.0029,
    "tts_fee": 0,
    "network": {
        "name": "Verizon Wireless:6006 - SVR/2",
        "type": "wireless"
    },
    "foreign_id": "<your system's id>"
}

Example Webhook (Failed Delivery):

{
    "drop_id": "5c8ee427a8d9ef4758bfaca5",
    "phone_number": "[phone]",
    "attempt_date": "2019-03-18T00:20:26.000Z",
    "status": "failure",
    "reason": "Invalid message",
    "dnc": false,
    "spam": false,
    "product_cost": 0,
    "compliance_fee": 0.0029,
    "tts_fee": 0,
    "network": {
        "name": "Verizon Wireless:6006 - SVR/2",
        "type": "wireless"
    },
    "foreign_id": "<your system's id>"
}

---

Possible Error Reasons

The following error codes will be returned to your webhook:

Name

Description

Invalid message

The contents of your SMS message are not acceptable or violate S.H.A.F.T

Spam detected

The phone carrier determined your message is spam.

Invalid caller ID or not SMS enabled

SMS does not support arbitrary caller IDs. You must use a phone number rented from Drop Cowboy as your caller ID.

No Funds

Your Drop Cowboy account is out of money.

Known Litigator

The phone number is a known TCPA litigator.

Prohibited by carrier or not SMS enabled

The phone number does not support SMS or the carrier blocked delivery of your message.

Message too long

Your message must be less than 160 characters in length.

Opted out

The phone number opted-out from receiving SMS from you.

Internal DNC

The phone number is on your Drop Cowboy DNC list and therefore blocked.

Temporarily unreachable

The phone number is experiencing a localized service outage.

Too Many

You tried to send to the same phone number more than 3 times in 3 days.

Unregistered Brand

You didn't pass brand_id or your brand is not registered yet.