API reference / Track results
Webhooks
Webhooks push events to your server as they happen: a voicemail sent, a text
failed, a contact replied, an AI agent finished a call. They tell you the
result of a send, because send routes answer 202 before anything is sent.
Manage subscriptions
| Route | Scope | Purpose |
|---|---|---|
POST /register/public/webhooks |
webhooks:write |
Create a webhook |
GET /register/public/webhooks |
webhooks:read |
List webhooks |
GET /register/public/webhooks/{id} |
webhooks:read |
One webhook |
PUT /register/public/webhooks/{id} |
webhooks:write |
Change a webhook's URL, events or name |
DELETE /register/public/webhooks/{id} |
webhooks:write |
Delete a webhook |
POST /register/public/webhooks/{id}/rotate-secret |
webhooks:write |
New signing secret |
GET /register/public/account/webhook-signing-secret |
webhooks:read |
Every signing secret |
A webhook is one URL, the event types it receives and its own signing secret. An account holds up to 50, like API keys, several on the same event type included. Webhooks added under Developers > Webhooks are the same records, so you can list, read, update and delete them here. Automation-managed webhooks are not included.
Create a webhook
curl -X POST https://api-v2.dropcowboy.com/register/public/webhooks \
-H "x-key: $DC_KEY" -H "x-secret: $DC_SECRET" \
-H "Content-Type: application/json" \
-d '{ "hook_url": "https://hooks.example.com/dropcowboy",
"event_types": ["contact.rvm.status", "contact.rvm.receipt"] }'
The 201 response holds webhook_id, name, hook_url, event_types,
hook_type, team_id, created_at, created_by,
signing_secret_created_at and signing_secret. Store the secret: list and
get never return it.
hook_urlis required: an absolutehttporhttpsURL (up to 2048 characters) that answers2xxwithin 5 seconds.event_typeslists ids fromGET /register/public/events, or["*"]for all. An unknown id is a400, listed indetails.invalid_event_types.hook_typeis shorthand for a one-item list and must also be an event id; send one of the two. In a response it is the id when there is exactly one, elsenull.nameis optional (1 to 100 characters), defaulting to the event id,All eventsorN events.- The 51st webhook is a
400(details.reason:webhook_limit_reached).
Get, update and delete take the webhook_id (an unknown one is a 404). List
returns an array, oldest first. Delete removes only that webhook and returns
{ "result": true }.
An event goes to every webhook that matches it: two webhooks on one event
type mean two deliveries, each with its own signature and the same X-Event-Id.
Update a webhook
PUT /register/public/webhooks/{id} changes a webhook in place. Send only
what changes:
curl -X PUT https://api-v2.dropcowboy.com/register/public/webhooks/9b2f6c1e-3d7a-4e58-a1c4-7f0e5d3b8a62 \
-H "x-key: $DC_KEY" -H "x-secret: $DC_SECRET" \
-H "Content-Type: application/json" \
-d '{ "hook_url": "https://hooks.example.com/dropcowboy-v2",
"event_types": ["contact.rvm.status", "contact.sms.status"] }'
Every field is optional, but send at least one: hook_url, event_types (or
hook_type, not both) and name, under the same rules as on create.
event_types replaces the whole set, so list every event the webhook
should receive.
The 200 response is the webhook without signing_secret. The webhook_id
and secret don't change; rotate the secret to
change it. An empty body is a 400 (details.reason: nothing_to_update), as is
an unknown event or a bad URL; an unknown id is a 404. The limit of 50
applies only to create.
Rotate a signing secret
POST /register/public/webhooks/{id}/rotate-secret takes no body and returns
webhook_id, signing_secret and signing_secret_created_at. The old
secret stops verifying at once, so update your receiver or accept both
(Several secrets).
What a delivery looks like
Each delivery is a POST with a JSON body:
{
"event_id": "d1f3a8e2-7c4b-4f9a-9d22-9c1e2f3a4b5c",
"event": "contact.rvm.status",
"event_at": 1774041600000,
"data": {
"contact_id": "5a4b3c2d-1e0f-4a9b-8c7d-6e5f4a3b2c1d",
"drop_id": "6ae22fc9b41d3e0a7c5f9e21",
"campaign_id": "a9c3e8f1-4b2d-4a7c-8e9b-1c2d3e4f5a6b",
"campaign_type": "rvm",
"status": "success",
"reason": "",
"reason_code": 0,
"to": "+13125550142",
"from": "+12125550100",
"network": {
"name": "Verizon Wireless",
"type": "wireless",
"mno": "VERIZON",
"network_id": "10038"
}
}
}
| Field | Meaning |
|---|---|
event_id |
UUID for this event. The same on every attempt and for every webhook that receives it, so use it to skip duplicates. |
event |
The event type |
event_at |
When it happened, in epoch milliseconds |
operation_id |
Only on bulk events. See Bulk events. |
data |
The event payload |
Match an event to your send on the foreign_id you set. Events don't carry
the 202's message_id. On an API send, campaign_id is the same on every
send, so don't match on it.
Status and receipt events carry the same foreign_id and contact_id as
callback_url: your foreign_id, else the contact's Record ID field, else
null. A send to a bare number names the one contact on your team with it,
and none if several share it.
A send that was looked up also carries network, the recipient's carrier:
name (the carrier that holds the number), type (wireless or landline),
and mno plus network_id when that carrier is one the campaign registry
tracks. A request refused before the lookup has no network. The same object
is on callback_url.
Status events also carry team, user, contact, list and
campaign_session objects (null when the id is). They exist for
automations; build on the flat fields above.
Headers on every delivery:
| Header | Value |
|---|---|
X-Signature |
sha256=<hex digest> |
X-Timestamp |
Unix time in seconds when the delivery was signed |
X-Signature-Version |
v1 |
X-Event-Id |
Same as event_id |
X-Attempt |
1 for the first try, then 2, 3 |
User-Agent |
DropCowboy-Webhook/1.0 |
Verify the signature
The signature is HMAC-SHA256 over {timestamp}.{raw body}, keyed with the
signing secret of the webhook that delivered it.
Verify the raw bytes you received. Parsing the JSON and serializing it again can change spacing or key order, and then no signature matches.
The receivers below are also in the Drop Cowboy® examples on GitHub, in Node.js, Python and C#, with tests that run without an account.
Node.js (Express)
const express = require('express');
const crypto = require('crypto');
const app = express();
const SECRET = process.env.DROPCOWBOY_SIGNING_SECRET;
function verifyWebhook(rawBody, headers, secret) {
const signature = headers['x-signature'];
const timestamp = headers['x-timestamp'];
if (!signature || !timestamp) return false;
const age = Math.abs(Date.now() / 1000 - Number(timestamp));
if (!Number.isFinite(age) || age > 300) return false;
const expected = 'sha256=' + crypto.createHmac('sha256', secret)
.update(timestamp + '.')
.update(rawBody)
.digest('hex');
const a = Buffer.from(signature);
const b = Buffer.from(expected);
return a.length === b.length && crypto.timingSafeEqual(a, b);
}
// express.raw keeps req.body as the exact bytes that were signed.
app.post('/webhooks/dropcowboy', express.raw({ type: 'application/json' }), (req, res) => {
if (!verifyWebhook(req.body, req.headers, SECRET)) {
return res.status(401).end();
}
const event = JSON.parse(req.body.toString('utf8'));
res.status(200).json({ received: true });
});
Python (Flask)
import hashlib, hmac, os, time
from flask import Flask, request, abort
app = Flask(__name__)
SECRET = os.environ["DROPCOWBOY_SIGNING_SECRET"].encode()
def verify_webhook(raw_body: bytes, headers) -> bool:
signature = headers.get("X-Signature", "")
timestamp = headers.get("X-Timestamp", "")
if not signature or not timestamp:
return False
if abs(time.time() - int(timestamp)) > 300:
return False
expected = "sha256=" + hmac.new(
SECRET, timestamp.encode() + b"." + raw_body, hashlib.sha256
).hexdigest()
return hmac.compare_digest(signature, expected)
@app.post("/webhooks/dropcowboy")
def dropcowboy_webhook():
if not verify_webhook(request.get_data(), request.headers):
abort(401)
event = request.get_json()
return {"received": True}
C# (ASP.NET Core)
using System.Security.Cryptography;
using System.Text;
var app = WebApplication.CreateBuilder(args).Build();
var secret = Environment.GetEnvironmentVariable("DROPCOWBOY_SIGNING_SECRET") ?? "";
app.MapPost("/webhooks/dropcowboy", async (HttpRequest request) =>
{
using var buffer = new MemoryStream();
await request.Body.CopyToAsync(buffer);
var rawBody = buffer.ToArray();
var signature = request.Headers["X-Signature"].ToString();
var timestamp = request.Headers["X-Timestamp"].ToString();
if (!long.TryParse(timestamp, out var signedAt)) return Results.StatusCode(401);
if (Math.Abs(DateTimeOffset.UtcNow.ToUnixTimeSeconds() - signedAt) > 300) return Results.StatusCode(401);
var message = Encoding.UTF8.GetBytes(timestamp + ".").Concat(rawBody).ToArray();
var digest = HMACSHA256.HashData(Encoding.UTF8.GetBytes(secret), message);
var expected = Encoding.UTF8.GetBytes("sha256=" + Convert.ToHexString(digest).ToLowerInvariant());
if (!CryptographicOperations.FixedTimeEquals(expected, Encoding.UTF8.GetBytes(signature)))
return Results.StatusCode(401);
return Results.Json(new { received = true });
});
app.Run();
Several secrets
GET /register/public/account/webhook-signing-secret returns an array of
webhook_id, event_types, hook_type and signing_secret, one per webhook.
A receiver that serves several webhooks, or is mid-rotation, holds several
secrets: accept a delivery that verifies against any one.
If verification fails, see A webhook arrives but the signature doesn't verify.
Delivery and retries
Answer with any 2xx within 5 seconds. Do the real work after you
answer, from a job queue of your own.
| Your response | What happens |
|---|---|
2xx |
Delivered |
408, 429, 5xx, a timeout or a connection error |
Retried |
Any other status, for example 400, 401, 404, 410 |
Not retried |
A delivery is tried at most 3 times: immediately, about 1 minute later,
and about 5 minutes after that. Then it is dropped. A retry goes only to the
webhooks that failed; the ones that answered 2xx aren't sent the event
again. You can still receive the same event_id more than once, so make your
handler idempotent.
URLs that resolve to private, loopback or link-local addresses are never called.
To see each attempt and your server's response, open the Webhooks tab of your API logs. See Find a webhook delivery.
Endpoint pauses
Deliveries to an origin (scheme, host and port) pause when it keeps failing:
- 100 retriable failures in a row (timeouts,
5xx,429), or - 5 rejections in a row (other
4xx, for example401from a verifier with the wrong secret).
The first pause lasts 5 minutes; further ones last 15, 30, then 60. A successful delivery resets the counts. Events that occur during a pause are dropped. They aren't sent when the pause ends, so fix a failing endpoint quickly and reconcile from the API afterwards.
Results of your sends
A 202 from a send route means your request was received, not that anything
was sent. The delivery rules (calling hours, the contact frequency limit,
consent and your balance) are checked after it, and the result arrives as a
status event. Delivery rules explains each
rule.
Subscribe to the event for each channel you send on:
| You send | Subscribe to |
|---|---|
Ringless voicemail (POST /rvm) |
contact.rvm.status with campaign_type: rvm |
Voice broadcast (POST /voice-broadcast) |
contact.rvm.status with campaign_type: voice_broadcast |
AI call (POST /ai-broadcast) |
contact.rvm.status with campaign_type: ai_broadcast, plus one ai_agent.* event for the call |
| Proof of delivery, for any ringless voicemail, voice broadcast or AI call a voicemail system answered, or an AI call a person answered when the agent records calls | contact.rvm.receipt, once the recording is ready. See Proof of delivery. |
Texts (POST /sms) |
contact.sms.status. campaign_type is mms for a send with media. |
contact.email.status, plus contact.email.bounce, contact.email.bounce_hard and contact.email.complaint |
|
| AI agent calls | ai_agent.call.completed, ai_agent.call.failed, ai_agent.outcome.* (see AI agents) |
| Campaigns | The channel events above, plus campaign.started, campaign.paused, campaign.completed, campaign.results_settled |
Every call and text status event carries status (success or failure),
reason and reason_code. Outcomes says what each code means
and what to do.
{
"event": "contact.sms.status",
"data": {
"campaign_type": "sms",
"status": "failure",
"reason": "Too Many Attempts",
"reason_code": 4013,
"to": "+13125550142"
}
}
A 4013 status event also carries frequency_limit: the limit applied to
that send and the attempts counted. See
Contact frequency limit.
"frequency_limit": { "max_attempts": 3, "window_days": 3, "attempts_in_window": 3 }
A send that fails before anything is sent, such as 3027 (Idempotency Key
Conflict), still fires its status event, with drop_id set to null. to
is null too when the request named no number, or more numbers than one
request allows. A send with wrong credentials (3007) fires no event; it is
reported on callback_url only.
If you are on a BYOC team and signed the call with a certificate you
uploaded, contact.rvm.status also carries four STIR/SHAKEN fields.
contact.rvm.receipt copies the status snapshot, so it has the same four.
Live voice events (contact.call.*, contact.voicemail.received and the
ai_agent.call.*, ai_agent.session.completed and ai_agent.outcome.*
events) use the same four keys when the call was signed.
They are present only when that team signed; they are omitted (not null)
otherwise. Retail teams never receive them.
| Field | Meaning |
|---|---|
sti_identity |
The full SIP Identity header (PASSporT JWT plus info= x5u) |
sti_attestation |
A, B or C |
sti_orig_id |
The SHAKEN origid. Today it equals the SIP Call-ID. |
sip_call_id |
The SIP Call-ID |
These four are enough for an ITG traceback.
"sti_identity": "eyJhbGciOiJFUzI1NiIsInR5cCI6InBhc3Nwb3J0...;info=<https://cert.example.com/shaken.cer>;alg=ES256;ppt=shaken",
"sti_attestation": "B",
"sti_orig_id": "8e4a2c6f-9d1b-4f7e-b3a5-6c9e1f4d2b78",
"sip_call_id": "8e4a2c6f-9d1b-4f7e-b3a5-6c9e1f4d2b78"
BYOC teams also get route_attempts, the carriers each voicemail was offered
to. See Which carriers were tried.
For an email sent with POST /email/public/email, contact.email.status
starts at delivered when the email goes out. If the email is blocked before
it's sent, for example by an opt-out or your email frequency limit, you get one
contact.email.status with status: failure and a 5xxx reason_code
instead, with campaign_id and session_id set to null.
A send's callback_url is only for when each send needs its own address. It
gets one unsigned POST, and these events still fire. See
callback_url.
Inbound messages
contact.msg.received fires when a contact texts one of your numbers.
Replies such as STOP also fire contact.msg.opt_out.
data.sms holds the message. An MMS adds sms.media, one entry per file,
with metadata only and never a link. Fetch
GET /phone/public/sms/{sms_id} for a download link that works for 24 hours.
contact.msg.sent, which fires after a text reply, has
the same sms object. contact.sms.status carries no media.
{
"event": "contact.msg.received",
"data": {
"received_at": 1757932200000,
"sms": {
"sms_id": "8945b5d3-d4b9-435e-ab6d-a21bb5b9b628",
"sms_type": "inbound",
"from": "+13125550142",
"to": "+14155550120",
"sms_body": "Here is the photo.",
"media": [
{ "media_id": "a9c3e8f1-4b2d-4a7c-8e9b-1c2d3e4f5a6b", "content_type": "image/jpeg", "size": 184220, "width": 1024, "height": 768, "duration_sec": null, "scan_status": "pending" }
]
}
}
}
media is absent on a plain text. Inbound files are scanned for malware after
they arrive, so scan_status is usually pending on this event. It changes
to clean or infected shortly after, with no further webhook. The message
read returns a link only once a file is clean.
Bulk events
Changes that can touch many contacts at once (imports, bulk list adds,
contact.created, contact.updated, contact.list.added,
contact.list.removed, contact.pipeline.stage.entered,
contact.pipeline.stage.exited) arrive as one event per operation, not
one per contact. They carry:
operation_idon the envelope, shared by every event from the same operation (an import emitscontact.created,contact.list.addedandcontact.import.completewith oneoperation_id);data.total_countand up to 25 contacts indata.contacts;data.truncated,data.next_cursorand, for list events,data.more_via, a ready-made URL forGET /contact/public/lists/{list_id}/contacts?after_id={cursor}to page through the rest.
While Drop Cowboy provides tools to support compliance efforts, customers remain solely responsible for obtaining proper consent, maintaining opt-out lists, and complying with all federal and state telemarketing regulations. Consult with your legal counsel to ensure your specific use case and consent mechanisms comply with applicable laws.
This information is for educational purposes only and does not constitute legal advice. Regulations vary by jurisdiction and use case. Always consult with qualified legal counsel to ensure your specific practices comply with applicable federal and state laws.