coss.comdocs

Poll a webhook listener

POST
/v1/webhook_listeners/{id}/poll

Acknowledges deliveries handed out earlier, keeps the listener open for another 10 minutes, and waits up to wait_ms (at most 25 s) for events. Deliveries come oldest first; one not acknowledged within two minutes is handed out again (with the same event_id). The answer may come early, with no deliveries, when the API restarts: poll again. Polls are not request-logged; each acknowledgement is logged as a webhook.forward line.

Authorization

bearerAuth
headerAuthorizationBearer <token>

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

Path Parameters

id*string

The webhook listener's id.

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
acks?array<>

What happened to deliveries handed out earlier. A delivery is finished once acknowledged: a 2xx status (or none, with no error) succeeds; anything else fails. Neither is retried.

Itemsitems <= 50
wait_ms?integer

How long to wait for deliveries when none is pending, in milliseconds. Default 20000, at most 25000.

Range0 <= value <= 25000
limit?integer

The most deliveries to hand out. Default 10, at most 50.

Range1 <= value <= 50

Response Body

Deliveries to forward (possibly none).

application/json
  1. response
object*"webhook_listener_poll"
Value in"webhook_listener_poll"
listener*
deliveries*array<>

Events to forward, oldest first. Empty when none arrived while the poll waited. A delivery not acknowledged within two minutes is handed out again.

acknowledged*integer

How many of the request's acknowledgements were recorded.

import { Coss } from "coss";const coss = new Coss({  apiKey: process.env.COSS_API_KEY,  baseUrl: "https://api.coss.com",});const { data, error } = await coss.webhookListeners.poll("whlis_01k7c8m4q2f3e9v6t5r1n0p8yz", {  acks: [    {      delivery_id: "whlisdel_01k7c8n2b5d7f9h1k3m5p7r9tv",      ack_token: "mfz3k2a8",      status_code: 200,      duration_ms: 12,      error: null,    },  ],  wait_ms: 20000,});
{  "object": "webhook_listener_poll",  "listener": {    "object": "webhook_listener",    "id": "whlis_01k7c8m4q2f3e9v6t5r1n0p8yz",    "api_version": "2026-10-10",    "event_types": [      "email.delivered",      "email.bounced"    ],    "description": "bailey-mbp → localhost:3000/webhooks",    "expires_at": "2026-01-15T09:40:00.000Z",    "created_at": "2026-01-15T09:30:00.000Z"  },  "deliveries": [    {      "object": "webhook_listener_delivery",      "id": "whlisdel_01k7c8n2b5d7f9h1k3m5p7r9tv",      "ack_token": "mfz3k2a8",      "event_id": "evt_01k7c8n1z4c6e8g0j2l4n6q8sa",      "event_type": "email.delivered",      "attempt": 1,      "body": "{\"id\":\"evt_01k7c8n1z4c6e8g0j2l4n6q8sa\",\"object\":\"event\",\"type\":\"email.delivered\",\"api_version\":\"2026-10-10\",\"created_at\":\"2026-01-15T09:30:00.000Z\",\"data\":{\"email_id\":\"email_01k7c8m9x3a5c7e9g1j3l5n7q9\",\"recipient\":\"user@example.com\"}}",      "created_at": "2026-01-15T09:30:00.000Z"    }  ],  "acknowledged": 0}