v1

latestOpenAPI 3.0.32026-07-264469137.7 KB

Webhooks

Create a webhook endpoint

Register a URL to receive webhook events, and choose which events to subscribe to. The signing secret is returned once in the response. Requires the webhooks:write scope.

post/v1/webhooks/endpoints

Request body

namestring required

A label for the endpoint.

urlstring uri required

The HTTPS URL Bachs should deliver events to.

event_typesstring[] required

The events to subscribe to. At least one is required.

Example request

{
  "name": "Production events",
  "url": "https://api.example.com/webhooks/bachs",
  "event_types": [
    "collection.succeeded",
    "collection.failed"
  ]
}

Response

The created endpoint, including its signing secret.

endpoint_idstring required

Unique identifier for the endpoint.

namestring required

A label for the endpoint.

urlstring uri required

The HTTPS URL events are delivered to.

enabledboolean required

Whether the endpoint is active and receiving events.

event_typesstring[] required

The events this endpoint is subscribed to.

created_atstring required

When the endpoint was created, in UTC.

updated_atstring required

When the endpoint was last updated, in UTC.

signing_secretstring required

The secret used to sign deliveries to this endpoint. Shown only here, on creation. Use it to verify the X-Bachs-Signature header.

Example response

{
  "endpoint_id": "whe_1a2b3c4d5e",
  "name": "Production events",
  "url": "https://api.example.com/webhooks/bachs",
  "enabled": true,
  "event_types": [
    "collection.succeeded",
    "collection.failed"
  ],
  "created_at": "2026-04-27T12:00:00Z",
  "updated_at": "2026-04-27T12:00:00Z",
  "signing_secret": "whsec_1a2b3c4d5e6f7g8h"
}