> For the complete documentation index, see [llms.txt](https://drop-cowboy.gitbook.io/drop-cowboy-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://drop-cowboy.gitbook.io/drop-cowboy-docs/api/sending-sms-text-message/webhooks.md).

# Webhooks

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 <a href="#linking-webhook-results" id="linking-webhook-results"></a>

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 <mark style="color:$success;">(Successful Delivery)</mark>: <a href="#example-webhook-success" id="example-webhook-success"></a>

```json
{
    "drop_id": "5c8eb7940a057a4ab0823e1a",
    "phone_number": "+15552224444",
    "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 <mark style="color:red;">(Failed Delivery)</mark>: <a href="#example-webhook-fail" id="example-webhook-fail"></a>

```json
{
    "drop_id": "5c8ee427a8d9ef4758bfaca5",
    "phone_number": "+15552224444",
    "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 <a href="#possible-error-codes" id="possible-error-codes"></a>

The following error codes will be returned to your webhook:

{% columns %}
{% column width="25%" valign="middle" %}

### <mark style="color:$primary;">**Name**</mark>

{% endcolumn %}

{% column width="74.99999999999997%" valign="middle" %}

### <mark style="color:$primary;">**Description**</mark>

{% endcolumn %}
{% endcolumns %}

{% columns %}
{% column width="25%" valign="middle" %}
Invalid message
{% endcolumn %}

{% column width="74.99999999999997%" %}
The contents of your SMS message are not acceptable or violate S.H.A.F.T
{% endcolumn %}
{% endcolumns %}

{% columns %}
{% column width="25%" valign="middle" %}
Spam detected
{% endcolumn %}

{% column width="74.99999999999997%" %}
The phone carrier determined your message is spam.
{% endcolumn %}
{% endcolumns %}

{% columns %}
{% column width="25%" valign="middle" %}
Invalid caller ID or not SMS enabled
{% endcolumn %}

{% column width="74.99999999999997%" %}
SMS does not support arbitrary caller IDs. You must use a phone number rented from Drop Cowboy as your caller ID.
{% endcolumn %}
{% endcolumns %}

{% columns %}
{% column width="25%" valign="middle" %}
No Funds
{% endcolumn %}

{% column width="74.99999999999997%" %}
Your Drop Cowboy account is out of money.
{% endcolumn %}
{% endcolumns %}

{% columns %}
{% column width="25%" valign="middle" %}
Known Litigator
{% endcolumn %}

{% column width="74.99999999999997%" %}
The phone number is a known TCPA litigator.
{% endcolumn %}
{% endcolumns %}

{% columns %}
{% column width="25%" valign="middle" %}
Prohibited by carrier or not SMS enabled
{% endcolumn %}

{% column width="74.99999999999997%" %}
The phone number does not support SMS or the carrier blocked delivery of your message.
{% endcolumn %}
{% endcolumns %}

{% columns %}
{% column width="25%" valign="middle" %}
Message too long
{% endcolumn %}

{% column width="74.99999999999997%" %}
Your message must be less than 160 characters in length.
{% endcolumn %}
{% endcolumns %}

{% columns %}
{% column width="25%" valign="middle" %}
Opted out
{% endcolumn %}

{% column width="74.99999999999997%" %}
The phone number opted-out from receiving SMS from you.
{% endcolumn %}
{% endcolumns %}

{% columns %}
{% column width="25%" valign="middle" %}
Internal DNC
{% endcolumn %}

{% column width="74.99999999999997%" %}
The phone number is on your Drop Cowboy DNC list and therefore blocked.
{% endcolumn %}
{% endcolumns %}

{% columns %}
{% column width="25%" valign="middle" %}
Temporarily unreachable
{% endcolumn %}

{% column width="74.99999999999997%" %}
The phone number is experiencing a localized service outage.
{% endcolumn %}
{% endcolumns %}

{% columns %}
{% column width="25%" valign="middle" %}
Too Many
{% endcolumn %}

{% column width="74.99999999999997%" %}
You tried to send to the same phone number more than 3 times in 3 days.
{% endcolumn %}
{% endcolumns %}

{% columns %}
{% column width="25%" valign="middle" %}
Unregistered Brand
{% endcolumn %}

{% column width="74.99999999999997%" %}
You didn't pass brand\_id or your brand is not registered yet.
{% endcolumn %}
{% endcolumns %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://drop-cowboy.gitbook.io/drop-cowboy-docs/api/sending-sms-text-message/webhooks.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.