coss.comdocs

Send a message

POST
/v1/hooks/applications/{application}/messages

Queues a message to the application: COSS delivers it to each of its enabled endpoints subscribed to event_type within seconds, signed with each endpoint's secret, and retries failures with backoff for about a day. Each request's webhook-id header is the message's id. Counts against the send quota once per endpoint it goes to (at least once). Live sends are refused while the organization is suspended (account_suspended). Hooks resources belong to the API key's own environment: a coss_test_… key only ever sees sandbox ones, a coss_live_… key only production ones.

Authorization

bearerAuth
headerAuthorizationBearer <token>

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

Path Parameters

application*string

The application's id (happ_…) or your uid for it.

Header Parameters

Idempotency-Key?string

Makes retries safe: a repeated request with the same key and body returns the original message instead of sending again, for 24 hours. 1-256 characters.

Length1 <= length <= 256
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_type*string

What happened, e.g. invoice.paid. Endpoints that filter by type only get the types they chose. The type doesn't have to be registered.

Match^[A-Za-z0-9_.-]{1,64}$
payload*

The JSON object delivered as the request body (at most 256 KB serialized). It is parsed and serialized again: send integers beyond 2^53 as strings.

Response Body

The message, queued for delivery.

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

Also the webhook-id header of every request delivering it.

application_id*string
event_type*string
payload*

The JSON body delivered to each endpoint.

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.hooks.messages.send({  application: "customer_8812",  event_type: "invoice.paid",  payload: {    invoice_id: "in_1042",    amount: 4200,    currency: "usd",  },});
{  "object": "hook_message",  "id": "hmsg_01k7c8m4q2f3e9v6t5r1n0p8yz",  "application_id": "happ_01k7c8m4q2f3e9v6t5r1n0p8yz",  "event_type": "invoice.paid",  "payload": {    "invoice_id": "in_1042",    "amount": 4200,    "currency": "usd"  },  "created_at": "2026-01-15T09:30:00.000Z"}