Roll a signing secret
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.
bearerAuthAuthorizationBearer <token>A secret API key from the dashboard: coss_live_… for production environments, coss_test_… for sandbox environments.
id*stringThe webhook endpoint's id.
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
previous_secret_expires_in?integerSeconds the current secret keeps signing deliveries next to the new one, so receivers can switch without rejecting anything. Default 86400 (a day), at most 604800 (a week). 0 stops it immediately, e.g. after a leak.
0 <= value <= 604800The endpoint and its new 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.rollSecret("whep_01k7c8m4q2f3e9v6t5r1n0p8yz", { previous_secret_expires_in: 3600,});{ "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…"}Retry a delivery POST
Queues a finished delivery (`succeeded` or `failed`) for one more attempt, made within seconds, signed with the endpoint's current secret and sent to its current URL. A delivery that is still `pending` is returned unchanged: it is already scheduled for `next_attempt_at` (automatic retries stop after 8 attempts).
Update a webhook endpoint PATCH
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.