Skip to main content
POST
Register a webhook subscription
Coming soon: The Webhooks API is currently under design review. This documentation describes the target interface and may change before release.

Overview

Registers an HTTPS endpoint to receive webhook events. You choose which event types the subscription will receive.
Important: the response includes the signingSecret used to sign every webhook payload sent to this subscription. It is only returned on creation and on rotation — store it securely. See Verifying Signatures.
Important: the endpoint URL must use HTTPS.

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json
url
string<uri>
required

The HTTPS endpoint that will receive the webhook calls. Must use HTTPS.

Example:

"https://partner.example.com/cobee/webhooks"

eventTypes
enum<string>[]
required

The event types this subscription will receive.

Minimum array length: 1
Available options:
employee.consumption.registered,
company.payroll-cycle.closed,
employee.committed-expense.requested,
employee.committed-expense.finished,
employee.committed-expense.cancelled,
employee.committed-expense.payment.cancelled
Example:

Response

Webhook subscription successfully created. The signing secret is only returned on creation and rotation — store it securely.

id
string<uuid>
required

The unique identifier of the subscription.

Example:

"c3d4e5f6-a1b2-4c3d-8e5f-6a7b8c9d0e1f"

url
string<uri>
required

The HTTPS endpoint that will receive the webhook calls.

Example:

"https://partner.example.com/cobee/webhooks"

eventTypes
enum<string>[]
required

The event types this subscription will receive.

Available options:
employee.consumption.registered,
company.payroll-cycle.closed,
employee.committed-expense.requested,
employee.committed-expense.finished,
employee.committed-expense.cancelled,
employee.committed-expense.payment.executed,
employee.committed-expense.payment.cancelled
status
enum<string>
required

The status of the subscription.

Available options:
enabled,
disabled
Example:

"enabled"

signingSecret
string
required

The secret used to sign webhook payloads (HMAC-SHA256). Only returned on creation and rotation.

Example:

"whsec_5257a869e7ecebeda32affa62cdca3fa"

createdAt
integer<timestamp>
required

When the subscription was created, in timestamp format.

Example:

1753939051