Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Webhook Management

Configure webhook endpoints and their event subscriptions.

List Webhooks

get
Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Responses
200

Every live endpoint this business holds, across all event families.

application/json
statusstringOptionalDefault: success
get/api/v2/webhooks
GET /api/v2/webhooks HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "status": "success",
  "data": [
    {
      "id": "018f3c1e-6b2a-7d48-9f3c-1e6b2a7d4f80",
      "business_id": "018e2b0d-5a19-7c37-8e2b-0d5a197c3760",
      "event_type": "travel_rule",
      "webhook_url": "https://partner.example.com/ospree/webhooks",
      "event_names": [
        "INCOMING_TRANSFER",
        "TRANSFER_COMPLETED"
      ],
      "ip_allowlist": [
        "203.0.113.7"
      ],
      "modified_by": "ops@partner.example.com",
      "last_modified": "2026-08-31T11:02:05Z",
      "webhook_desc": "Travel rule events"
    },
    {
      "id": "018f3c1e-6b2a-7d48-9f3c-1e6b2a7d4f81",
      "business_id": "018e2b0d-5a19-7c37-8e2b-0d5a197c3760",
      "event_type": "address_verification",
      "webhook_url": "https://partner.example.com/ospree/address-verification",
      "webhook_desc": "Address verification events"
    }
  ]
}

Configure Webhook

post

Upsert this business's webhook endpoint for one event family.

An upsert with no id, and deliberately not a create: it updates the family's endpoint, or creates one when the family has none. A family may hold several endpoints, up to a maximum of 5, but this call never adds the second one — it answers 409 rather than overwriting an arbitrary one of them.

Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Body

Configure this business's webhook endpoint for one event family. The call is an upsert and carries no endpoint id: it updates the endpoint the family already has, and creates one when it has none. A business may hold up to 5 endpoints per event family, but this route never creates a second one — when the family already holds more than one endpoint it answers 409 rather than guessing which to overwrite. Use GET /webhooks to list them and DELETE /webhooks/{id} to address one by id.

webhook_urlstringRequired
event_namesstring[] · nullableOptional
ip_allowliststring[] · nullableOptional
event_typeintegerRequired
Responses
201

The endpoint was created or updated.

application/json
statusstringOptionalDefault: success
post/api/v2/webhooks
POST /api/v2/webhooks HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 164

{
  "event_type": 1,
  "webhook_url": "https://partner.example.com/ospree/webhooks",
  "event_names": [
    "INCOMING_TRANSFER",
    "TRANSFER_COMPLETED"
  ],
  "ip_allowlist": [
    "203.0.113.7"
  ]
}
{
  "status": "success",
  "data": {
    "id": "018f3c1e-6b2a-7d48-9f3c-1e6b2a7d4f80",
    "event_type": 1,
    "business_id": "018e2b0d-5a19-7c37-8e2b-0d5a197c3760",
    "webhook_url": "https://partner.example.com/ospree/webhooks",
    "event_names": [
      "INCOMING_TRANSFER",
      "TRANSFER_COMPLETED"
    ],
    "ip_allowlist": [
      "203.0.113.7"
    ],
    "created_by": "018d1a9c-4908-7b26-9d1a-9c49087b2650",
    "created": "2026-08-31T09:14:22Z",
    "webhook_secret": "the plaintext signing secret, returned by this call only"
  }
}

Rotate Webhook Secret

post

Mint a replacement signing secret and hold it pending — phase one of two.

The response is the only time this secret is ever disclosed. Ospree keeps signing deliveries with the current secret until the activate call below, so nothing breaks while the new value is deployed to the tenant's verifier.

Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Path parameters
idstringRequired
Responses
200

A replacement secret was minted and is pending activation.

application/json
statusstringOptionalDefault: success
post/api/v2/webhooks/{id}/secret/rotate
POST /api/v2/webhooks/{id}/secret/rotate HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "status": "success",
  "data": {
    "id": "018f3c1e-6b2a-7d48-9f3c-1e6b2a7d4f80",
    "webhook_secret": "the replacement signing secret, returned by this call only",
    "expires": "2026-09-30T09:00:00Z"
  }
}

Activate Webhook Secret

post

Promote the pending signing secret to active — phase two, the cutover.

Carries no secret material: the pending value was disclosed by the rotate that minted it and by nothing else.

Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Path parameters
idstringRequired
Responses
200

The pending secret is now the active signing secret.

application/json
statusstringOptionalDefault: success
post/api/v2/webhooks/{id}/secret/activate
POST /api/v2/webhooks/{id}/secret/activate HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "status": "success",
  "data": {
    "id": "018f3c1e-6b2a-7d48-9f3c-1e6b2a7d4f80",
    "event_type": 1,
    "business_id": "018e2b0d-5a19-7c37-8e2b-0d5a197c3760",
    "webhook_url": "https://partner.example.com/ospree/webhooks",
    "event_names": [
      "INCOMING_TRANSFER",
      "TRANSFER_COMPLETED"
    ],
    "ip_allowlist": [
      "203.0.113.7"
    ],
    "created_by": "018d1a9c-4908-7b26-9d1a-9c49087b2650",
    "created": "2026-08-31T09:14:22Z",
    "modified_by": "018d1a9c-4908-7b26-9d1a-9c49087b2650",
    "last_modified": "2026-08-31T12:40:11Z"
  }
}

List Webhook Event Types

get
Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Responses
200

The event families a webhook can be registered for.

application/json
statusstringOptionalDefault: success
get/api/v2/webhooks/event_types
GET /api/v2/webhooks/event_types HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "status": "success",
  "data": [
    {
      "event_type_name": "travel_rule",
      "event_type_id": "1"
    },
    {
      "event_type_name": "address_verification",
      "event_type_id": "3"
    }
  ]
}

Delete Webhook

delete
Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Path parameters
idstringRequired
Responses
200

The endpoint was deleted. data is the outcome flag.

application/json
statusstringOptionalDefault: success
databoolean · nullableOptional
delete/api/v2/webhooks/{id}
DELETE /api/v2/webhooks/{id} HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "status": "success",
  "data": true
}

Last updated