Create a webhook

POST/api/v2/webhooks

Subscribes a URL to events. The response carries the signing secret once. A subscription created here receives v2 bodies. Needs webhooks:write, plus payouts:read to receive payout events and counterparties:read to receive counterparty events. The webhook receives events only while the credential that created or last updated it can read them.

Header Parameters

idempotency-key?maxLength(255)

Client-chosen key, 1 to 255 characters (a UUID is recommended). The same key on the same endpoint within 24 hours replays the stored response with Idempotent-Replayed: true.

Length1 <= length <= 255

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

url*maxLength(2048)

Where Talentir sends the events: a public https URL. Private and reserved hosts are refused.

Formaturi

Lengthlength <= 2048

events*array<>

The events to receive, at least one. payout.* matches every payout event, * every event.

Items1 <= items

Response Body

`application/json`

curl -X POST "https://example.com/api/v2/webhooks" \  -H "Content-Type: application/json" \  -d '{    "url": "https://example.com/done",    "events": [      "payout.*"    ]  }'

{  "object": "webhook",  "id": "webhook_0e4ba886-0bfe-4b6a-ae2e-d6d9d135dd1e",  "url": "https://example.com/done",  "events": [    "string"  ],  "enabled": true,  "secret": "string",  "createdAt": "2026-09-24T10:00:00.000Z",  "updatedAt": "2026-09-24T10:00:00.000Z"}

Header Parameters

Request Body

Response Body

201application/json

400application/json

401application/json

403application/json

404application/json

409application/json

500application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`