POST/v1/webhooks

Create a webhook endpoint

Registers an https endpoint (at most 20 per organisation) with the event subscription (types, families such as item.*, or *) and optional filters on Postflow, Postbatch and test mode. The response carries the signing secret once.

Scope webhooks.manage

Body

urlstringrequiredmax length 2000

descriptionstringmax length 200

eventsarray of stringrequiredmin items 1max items 60

filtersobject

4 fields

postflowIdstringmin length 1max length 40

postbatchIdstringmin length 1max length 40

isTestboolean

integrationInstallationIdstringmin length 1max length 40

activeboolean

Returns

13 fields of the 201 answer

idstringrequired

urlstringrequired

descriptionstring or nullrequired

eventsarray of stringrequired

filtersobjectrequired

4 fields

postflowIdstring

postbatchIdstring

isTestboolean

integrationInstallationIdstring

activebooleanrequired

failureStreakintegerrequired

disabledAtdate-time or nullrequired

lastDeliveryAtdate-time or nullrequired

lastStatusenum or nullrequired

SUCCEEDEDFAILEDEXHAUSTED

createdAtdate-timerequired

updatedAtdate-timerequired

secretstringrequired

Responses

201Success

401Authentication required or API key invalid

403Permission or scope missing, organisation suspended

422Validation failed

429Rate limited for this API key and class; wait Retry-After seconds

otherError (RFC 9457 problem details)

curl -X POST https://api.postbuddy.nl/v1/webhooks \ -H "Authorization: Bearer $POSTBUDDY_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "url": "https://example.com/r/Fq3ZtR8w", "description": "Welcome card for new customers", "events": [ "Example" ] }'

import { PostBuddyClient } from '@postbuddy/sdk'; const client = new PostBuddyClient({ apiKey: process.env.POSTBUDDY_API_KEY! }); const result = await client.webhooks.create({ body: { url: 'https://example.com/r/Fq3ZtR8w', description: 'Welcome card for new customers', events: [ 'Example', ], }, });

import os from postbuddy import Client client = Client(os.environ["POSTBUDDY_API_KEY"]) result = client.webhooks.create({ "url": "https://example.com/r/Fq3ZtR8w", "description": "Welcome card for new customers", "events": [ "Example", ], })

{ "id": "wh_01J9Y2K8QF4T6W8Z0B2D4F6H8K", "url": "https://example.com/r/Fq3ZtR8w", "description": "Welcome card for new customers", "events": [ "Example" ], "filters": { "postflowId": "pf_01J9Y2K8QF4T6W8Z0B2D4F6H8K", "postbatchId": "pb_01J9Y2K8QF4T6W8Z0B2D4F6H8K", "isTest": false, "integrationInstallationId": "obj_01J9Y2K8QF4T6W8Z0B2D4F6H8K" }, "active": true, "failureStreak": 1, "disabledAt": "2026-10-16T09:14:02.000Z", "lastDeliveryAt": "2026-10-16T09:14:02.000Z", "lastStatus": "SUCCEEDED", "createdAt": "2026-10-16T09:14:02.000Z", "updatedAt": "2026-10-16T09:14:02.000Z", "secret": "whsec_9c1f2b7e4d" }

{ "type": "https://docs.postbuddy.nl/errors/validation_failed", "title": "Validation failed", "status": 422, "code": "validation_failed", "detail": "Validation failed", "requestId": "req_01J9Y2K8QF4T6W8Z0B2D4F6H8K", "errors": [ { "field": "recipient.postalCode", "code": "invalid_string", "message": "Invalid postal code" } ] }