COSS
Webhook endpoints

Update a webhook endpoint

PATCH
/v1/webhook_endpoints/{id}

Changes the URL, description, subscribed event types, API version or enabled flag. Omitted fields keep their current value, and the signing secret stays the same (see Roll a signing secret), so receivers keep verifying deliveries. Disabling an endpoint stops deliveries without losing its configuration.

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 endpoint'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
url?string

An https:// URL COSS posts events to.

Length1 <= length <= 2048
description?|

A note for your own reference. null clears it.

Lengthlength <= 256
event_types?array<>

Event types delivered to this endpoint. An empty array means every event type, including ones added later.

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

The API version (Coss-Version) events are rendered in for this endpoint. Each event carries it as api_version.

Value in"2026-10-10"
enabled?boolean

Response Body

The updated endpoint.

application/json
  1. response
object*"webhook_endpoint"
Value in"webhook_endpoint"
id*string
url*string
description*string|null
event_types*array<string>

Event types delivered to this endpoint. An empty array means every event type, including ones added later.

api_version*string

The API version (Coss-Version) events are rendered in for this endpoint. Each event carries it as api_version.

enabled*boolean

A 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.

Formatdate-time
created_at*string
Formatdate-time
updated_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.webhookEndpoints.update("whep_01k7c8m4q2f3e9v6t5r1n0p8yz", {  enabled: false,});
{  "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"}

Roll a signing secret POST

Replaces the endpoint's signing secret with a new one, returned in the response (the only time it is). Until `previous_secret_expires_at`, every delivery is signed with both secrets (`webhook-signature` lists two signatures), so receivers verifying with either one accept it: deploy the new secret, then let the old one expire. Rolling again in that time stops the older secret at once. Not idempotent: after a lost response, roll again.