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_url is required: an absolute http or https URL (up to 2048 characters) that answers 2xx within 5 seconds.
  • event_types lists ids from GET /register/public/events, or ["*"] for all. An unknown id is a 400, listed in details.invalid_event_types. hook_type is 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, else null.
  • name is optional (1 to 100 characters), defaulting to the event id, All events or N 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 example 401 from 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.
Email 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_id on the envelope, shared by every event from the same operation (an import emits contact.created, contact.list.added and contact.import.complete with one operation_id);
  • data.total_count and up to 25 contacts in data.contacts;
  • data.truncated, data.next_cursor and, for list events, data.more_via, a ready-made URL for GET /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.

Code samples

The requests from this page, ready to copy. Set DC_KEY and DC_SECRET to your API key pair first.

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"] }'
Update a webhook
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"] }'
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();