coss.comdocs

Open a webhook listener

POST
/v1/webhook_listeners

Listeners are how coss listen forwards events to a local server: COSS can't reach localhost, so the CLI pulls them. They belong to the API key's environment, receive events created after they open, and don't count toward the plan's webhook endpoints. A listener closes when it is deleted or after 10 minutes without a poll; an environment has at most 5 open at once. Events reach it unsigned: the CLI signs what it forwards with its own secret.

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

Event types to receive. Defaults to every event type.

Itemsitems <= 31
api_version?"2026-10-10"

The API version events are rendered in. Defaults to the version of the request that creates the listener.

Value in"2026-10-10"
description?|

Where the events go, for your own reference (shown in the log).

Lengthlength <= 256

Response Body

The listener.

application/json
  1. response
object*"webhook_listener"
Value in"webhook_listener"
id*string
api_version*string

The API version (Coss-Version) the listener's events are rendered in.

event_types*array<string>

Event types the listener receives. An empty array means every event type.

description*string|null
expires_at*string

When the listener closes unless it is polled again; every poll moves it 10 minutes ahead.

Formatdate-time
created_at*string
Formatdate-time
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.create({  event_types: [    "email.sent",    "email.delivered",  ],  description: "localhost:3000/webhooks",});
{  "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"}