Create a webhook endpoint
Registers a URL that receives signed event notifications. Webhook endpoints belong to the API key's own environment: a coss_test_… key only ever sees sandbox endpoints, and a coss_live_… key only production ones. The response carries the signing secret, which is returned only here and when it is rolled: store it, and verify every delivery with it (verifyWebhook in the SDK).
bearerAuthAuthorizationBearer <token>A secret API key from the dashboard: coss_live_… for production environments, coss_test_… for sandbox environments.
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.
"2026-10-10"application/json- body
url*stringAn https:// URL COSS posts events to.
1 <= length <= 2048description?|A note for your own reference. null clears it.
length <= 256event_types?array<>Event types delivered to this endpoint. An empty array means every event type, including ones added later. Defaults to every event type.
items <= 25api_version?"2026-10-10"The API version (Coss-Version) events are rendered in for this endpoint. Each event carries it as api_version. Defaults to the version of the request that creates the endpoint.
"2026-10-10"The endpoint and its signing secret.
application/json- response
object*"webhook_endpoint""webhook_endpoint"id*stringurl*stringdescription*string|nullevent_types*array<string>Event types delivered to this endpoint. An empty array means every event type, including ones added later.
api_version*stringThe API version (Coss-Version) events are rendered in for this endpoint. Each event carries it as api_version.
enabled*booleanA disabled endpoint receives nothing until it is enabled again.
previous_secret_expires_at*|After a secret roll, deliveries are also signed with the previous secret until this time. null when only the current secret signs.
date-timecreated_at*stringdate-timeupdated_at*stringdate-timesecret*stringThe endpoint's whsec_… signing secret, used to verify the requests COSS sends. Returned only when the endpoint is created and when its secret is rolled — store it now; it cannot be read back through the API.
import { Coss } from "coss";const coss = new Coss({ apiKey: process.env.COSS_API_KEY, baseUrl: "https://api.coss.com",});const { data, error } = await coss.webhookEndpoints.create({ url: "https://example.com/webhooks/coss", description: "Production receiver", event_types: [ "email.sent", "email.delivered", ],});{ "object": "webhook_endpoint", "id": "whep_01k7c8m4q2f3e9v6t5r1n0p8yz", "url": "https://example.com/webhooks/coss", "description": "Production receiver", "event_types": [ "email.delivered", "email.bounced" ], "api_version": "2026-10-10", "enabled": true, "previous_secret_expires_at": null, "created_at": "2026-01-15T09:30:00.000Z", "updated_at": "2026-01-15T09:30:00.000Z", "secret": "whsec_6Jk…"}Update the tracking default PATCH
Sets the environment default, which applies to emails without a rule for their category. Fields left out keep their value; if there is no default yet, it is created with them off. Settings belong to the API key's own environment: a `coss_test_…` key only ever changes sandbox settings. Emails keep the settings that applied when they were sent.
Delete a webhook endpoint DELETE
Removes the endpoint and its delivery log. Deliveries already queued for it are dropped. To stop deliveries temporarily, set `enabled` to `false` instead.