Webhooks
Get told when something happens instead of polling: webhook endpoints, event types, signature verification, retries and delivery logs.
Add webhook endpoints per environment in the dashboard (Webhooks) or through the API. Each
endpoint subscribes to event types (all of them by default) and has its own whsec_… signing
secret.
const { : , } = await ..({
: "https://example.com/webhooks/coss",
: ["email.delivered", "email.bounced"],
});
// Store the secret now: it is only returned when the endpoint is created (or its secret rolled).
const = ?.;Events
| Type | Sent when |
|---|---|
email.sent | The provider accepted the email |
email.delivered | A recipient's mail server accepted it |
email.delivery_delayed | Delivery to a recipient is being retried |
email.bounced | A recipient's mail server rejected it |
email.complained | A recipient marked it as spam |
email.failed | The email could not be sent at all |
email.suppressed | A recipient was skipped because it is suppressed |
email.scheduled | An email was scheduled for later |
email.rescheduled | A scheduled email got a new time (data.reschedule) |
email.canceled | A scheduled email was canceled |
email.opened | A recipient opened it (open tracking) |
email.clicked | A recipient clicked a tracked link (click tracking) |
email.unsubscribed | A recipient used one-click unsubscribe |
email.received | An email arrived at one of the environment's receiving addresses |
inbox.message.received | An email arrived in one of the environment's inboxes |
contact.created | A contact was added (one at a time: imports send no events) |
contact.updated | A contact's names, status, properties or topics changed |
contact.deleted | A contact was deleted |
contact.unsubscribed | A contact unsubscribed from all marketing email, or from one topic (topic), through the preference center or one-click unsubscribe |
contact.confirmed | A contact confirmed their address (double opt-in) |
broadcast.sending | A broadcast started sending |
broadcast.sent | A broadcast finished: every eligible contact was processed and none of its emails is still waiting (failures are in its stats) |
broadcast.paused | A broadcast was paused, by you or by coss.com (pause_reason) |
broadcast.canceled | A scheduled, sending or paused broadcast was canceled |
broadcast.failed | A broadcast stopped for good (error) |
sms.scheduled | An SMS was scheduled |
sms.sent | The carrier accepted an SMS |
sms.delivered | The carrier delivered it to the phone |
sms.undelivered | The carrier couldn't deliver it (data.failure) |
sms.failed | The SMS could not be sent at all (data.failure) |
sms.suppressed | The SMS was skipped because its number is suppressed (data.suppression) |
sms.canceled | A scheduled SMS was canceled |
sms.received | An SMS arrived at a number whose replies go to this environment (receiving) |
sms.opted_out | A number replied STOP and was suppressed in this environment |
sms.opted_in | A number replied START and its opt-out was removed |
sign_request.sent | A signature request was sent (created with send, or a draft sent) |
sign_request.viewed | A signer opened it for the first time (data.signer) |
sign_request.signer_signed | A signer signed (data.signer); data.status is completed when they were the last |
sign_request.declined | A signer declined, which declines the request (data.reason) |
sign_request.completed | Everyone signed and the sealed, signed document is ready to download |
sign_request.canceled | You canceled it |
sign_request.expired | It passed its expires_at before everyone signed |
verification.approved | The right code was checked (billed once) |
verification.failed | Too many wrong codes, or the code couldn't be sent (data.failure) |
verification.blocked | The fraud guard stopped it before a code was sent (data.reasons) |
form.submission.received | A form submission was accepted (data.data: what was submitted) |
form.submission.flagged | Risk held a submission for review or refused it as spam (data.spam_reason) |
scheduling.booking.confirmed | A booking was confirmed. Ids, times and statuses only: retrieve it for the attendee |
scheduling.booking.pending_approval | A booking is waiting for the host's approval |
scheduling.booking.rescheduled | A booking moved (data.previous_start) |
scheduling.booking.cancelled | A booking was cancelled |
scheduling.booking.declined | A booking was declined, or its approval deadline passed |
scheduling.booking.no_show | An attendee was marked as a no-show |
scheduling.booking.external_conflict | Something else landed on a booked time, or the host changed the event on their calendar |
scheduling.booking.calendar_write_failed | A booking couldn't be written to the host's calendar. It still stands |
scheduling.booking.location_ready | A booking's meeting link is ready |
scheduling.booking.reassigned | A booking went to another host (data.previous_host_ids) |
scheduling.reassignment.completed | Many bookings finished moving, or that was cancelled (data.counts) |
scheduling.booking.started | A confirmed booking's start time arrived. It doesn't mean anyone joined |
scheduling.booking.ended | A confirmed booking's end time arrived |
scheduling.booking.reminder | A reminder you timed came due (data.reminder) |
scheduling.calendar.connected | A host connected a calendar |
scheduling.calendar.needs_reauth | A host's calendar lost access: they aren't offered until it's back |
scheduling.calendar.disconnected | A host disconnected a calendar |
scheduling.out_of_office.created | A host was marked as away. Ids and times only: never why |
scheduling.out_of_office.updated | A host's time away changed |
scheduling.out_of_office.deleted | A host's time away was removed |
scheduling.out_of_office.started | A host's time away began |
scheduling.out_of_office.ended | A host's time away ended |
risk.assessment.review | A risk assessment decided review |
risk.assessment.reviewed | Feedback resolved a review |
hook_endpoint.disabled | coss.com disabled one of your Hooks applications' endpoints after its deliveries failed for 5 days |
Sub-account events
A sub-account's own reputation changes go to its environment's endpoints
(live only). data.subaccount_id and data.uid name it.
| Type | Sent when |
|---|---|
subaccount.reputation_warning | Its bounce or complaint rate crossed the warning threshold |
subaccount.reputation_recovered | The warning cleared |
subaccount.paused | Its live sending was paused (a rate, or content screening: data.trigger) |
subaccount.reinstated | You reinstated it |
Organization events
These concern the whole organization, so every live environment's endpoints receive them
(sandbox endpoints don't). data.organization_id names the organization.
| Type | Sent when |
|---|---|
domain.dmarc_report_received | A DMARC aggregate report about a domain arrived (a summary, no rows) |
account.reputation_warning | A reputation check (bounces, complaints, content) crossed its warning threshold |
account.reputation_recovered | The warning cleared |
account.suspended | Live sending was suspended |
account.reinstated | The suspension was lifted |
account.marketing_paused | The marketing stream's bounce or complaint rate paused marketing sends (data.marketing) |
account.marketing_reinstated | The marketing pause was lifted |
billing.invoice_finalized | An invoice was issued (data.invoice, without lines) |
billing.invoice_paid | An invoice was paid in full |
billing.invoice_payment_failed | Charging an invoice failed (data.failure.message); it is retried |
billing.invoice_voided | An open invoice was voided |
billing.plan_changed | The plan changed or a change was scheduled or undone (change, plan, effective_at) |
billing.usage_threshold_reached | Usage reached an alert threshold of the month's credit or Free's allowance (percent) |
billing.hold_placed | Live sending was paused for billing (reason: delinquent, spend_limit, credit_limit or admin) |
billing.hold_lifted | That pause ended |
billing.credit_granted | A credit was added (data.credit) |
billing.budget_threshold_reached | A member's, project's or API key's spend reached an alert threshold of its monthly budget (scope, target_id, percent) |
billing.budget_hold_placed | Its budget is used up: its live sending is paused (scope, target_id) |
billing.budget_hold_lifted | That pause ended (a new month, or a higher budget) |
See Plans and billing for what they mean and how to read the rest of an organization's billing.
The request body is a JSON event. Payloads describe the email (email_id, from, to, subject,
tags, category) but never include its content, headers, cc or bcc; email.received events
likewise only name the received email (received_email_id) and who sent it to whom. sms.*
events never include the text either: read it with coss.sms.get() or coss.sms.received.get(). sign_request.*
events never include documents or what signers filled in. Events are
rendered in the
endpoint's API version, named in api_version.
{
"id": "evt_01k7c8m4q2f3e9v6t5r1n0p8yz",
"object": "event",
"type": "email.delivered",
"api_version": "2026-10-10",
"created_at": "2026-10-10T12:00:01.000Z",
"data": {
"email_id": "email_01k7c8m4q2f3e9v6t5r1n0p8yz",
"from": "Acme <hello@acme.com>",
"to": ["user@example.com"],
"subject": "Welcome",
"tags": [],
"category": null,
"sandbox": false,
"recipient": "user@example.com",
"occurred_at": "2026-10-10T12:00:00.000Z",
"delivery": { "smtp_response": "250 2.0.0 OK" }
}
}Verifying requests
Requests are signed with Standard Webhooks headers:
webhook-id, webhook-timestamp and webhook-signature. Always verify them before trusting the
body. With the SDK, use verifyWebhook.
Testing locally
Your development server isn't reachable from the internet, so register no endpoint for it: run
coss listen --forward-to localhost:3000/webhooks, which receives the
environment's events and forwards them to your server, signed with a secret of its own that you
verify the same way.
To try a handler without making the real thing happen, send a test event with
coss trigger or the API: a sample event of that type, sent to
the environment's subscribed endpoints and open listeners exactly like a real one (same body,
signature, retries and log lines). Test events are for sandbox environments only, and of every
type except the live-only domain.*, account.* and billing.*. Nothing in the body marks them as
tests, and the ids in the sample are made up: pass real ones in data if your handler looks them
up.
const { } = await ..({
: "email.bounced",
: { : "ada@example.com" },
});
.(?.., ?., ?.);Rolling the secret
Roll an endpoint's secret in the dashboard (Roll secret on the endpoint) or through the API to
replace it, for example on a schedule or after it may have leaked. For a grace period (a day by
default, up to a week) every request carries two signatures, one per secret, in
webhook-signature, so a receiver verifying with either one keeps accepting requests while you
deploy the new secret. Choose 0 to stop the old secret at once.
const { : } = await ..(, {
: 60 * 60, // the old secret keeps signing for an hour
});
const = ?.; // deploy it before rolled?.previous_secret_expires_atRolling again during the grace period stops the older secret immediately. The SDK never retries a roll: if the response is lost, roll again and deploy that secret.
Delivery and retries
- Respond with any
2xxstatus within 10 seconds to acknowledge an event. - Failed deliveries are retried 7 times over about 28 hours (5 s, 5 min, 30 min, 2 h, 5 h, 10 h, 10 h).
- Events can arrive out of order: sort by
data.occurred_at(every event has it). - An event can arrive more than once: deduplicate by
id(equal to thewebhook-idheader). - Events about an email or text message sent with a
traceparentheader carry it indata.traceparentand as the request's owntraceparentheader (see Tracing).
Delivery logs
Every event sent to an endpoint is logged as a delivery, with each HTTP attempt (status code,
duration, error and the first 1 KB of your response) and the payload as sent. Find them on the
endpoint's page in the dashboard, or list them through the API — newest first, filtered by
status or event_id:
const { : } = await ...(, {
: "failed",
});
// After fixing your receiver, send a failed event again.
for (const of ?. ?? []) {
await ...(, .);
}A retry makes one more attempt within seconds, signed with the endpoint's current secret and sent to its current URL. Deleting an endpoint deletes its delivery log, and deliveries are deleted 30 days after the event (see data retention).
Last updated