coss.comdocs

Send a test event

POST
/v1/webhook_events/test

Sends a sample event of a type to the environment's enabled endpoints subscribed to it and its open listeners (coss listen), exactly as a real one is sent: same body, signature, retries and log lines. coss trigger calls it. Sandbox environments only. The ids in the sample are made up (pass real ones in data for a handler that looks them up), and nothing marks the event as a test: your handler takes it like the real thing. When nothing is subscribed, the event goes nowhere and isn't kept.

Authorization

bearerAuth
headerAuthorizationBearer <token>

A secret API key from the dashboard: coss_live_… for production environments, coss_test_… for sandbox environments.

Header Parameters

Coss-Version?"2026-10-10"

The API version (a date) to use for this request. Defaults to your organization's version, pinned to the latest one when it first used the API and upgraded from the dashboard. The SDK always sends the version it was built for.

Value in"2026-10-10"

Request Body

application/json
  1. body
type*string

The event type. domain.*, account.* and billing.* events only reach live environments, so they can't be tested in a sandbox one.

Value in"email.sent""email.delivered""email.delivery_delayed""email.bounced""email.complained""email.failed""email.suppressed""email.scheduled""email.canceled""email.opened""email.clicked""email.rescheduled""email.unsubscribed""email.received""domain.dmarc_report_received""account.reputation_warning""account.reputation_recovered""account.suspended""account.reinstated""account.marketing_paused""account.marketing_reinstated""hook_endpoint.disabled""billing.invoice_finalized""billing.invoice_paid""billing.invoice_payment_failed""billing.invoice_voided""billing.plan_changed""billing.usage_threshold_reached""billing.hold_placed""billing.hold_lifted""billing.credit_granted""risk.assessment.review""risk.assessment.reviewed""contact.created""contact.updated""contact.deleted""contact.unsubscribed""contact.confirmed""broadcast.sending""broadcast.sent""broadcast.paused""broadcast.canceled""broadcast.failed"
data?

Fields merged over the sample's data (objects field by field, anything else replaced), in the latest API version's shape: e.g. a real email_id, or the recipient your handler looks for. Unknown fields are refused.

Response Body

The event that was sent, and to how many receivers.

application/json
  1. response
object*"webhook_test_event"
Value in"webhook_test_event"
event*|||||

The event, as an endpoint on the request's API version receives it. Its webhook-id header is event.id.

endpoints*integer

Enabled endpoints of the environment subscribed to the type, each sent it once.

listeners*integer

Open coss listen listeners subscribed to the type, each handed it once.

import { Coss } from "coss";const coss = new Coss({  apiKey: process.env.COSS_API_KEY,  baseUrl: "https://api.coss.com",});const { data, error } = await coss.webhookEvents.test({  type: "email.bounced",  data: {    recipient: "ada@example.com",  },});
{  "object": "webhook_test_event",  "event": {    "id": "evt_01k7c8m4r0c2b8w9y3d5f6g7h8",    "object": "event",    "type": "email.bounced",    "api_version": "2026-10-10",    "created_at": "2026-10-10T12:00:03.000Z",    "data": {      "email_id": "email_01k7c8m4q2f3e9v6t5r1n0p8yz",      "from": "Acme <onboarding@acme.com>",      "to": [        "ada@example.com"      ],      "subject": "Welcome to Acme",      "tags": [        {          "name": "template",          "value": "welcome"        }      ],      "category": "onboarding",      "sandbox": true,      "recipient": "ada@example.com",      "occurred_at": "2026-10-10T12:00:03.000Z",      "bounce": {        "type": "permanent",        "sub_type": "General",        "diagnostic_code": "smtp; 550 5.1.1 The email account that you tried to reach does not exist"      }    }  },  "endpoints": 1,  "listeners": 1}