Create webhook subscription
Subscribe a target URL to one or more WundertreOS event types.
POST/api-webhook-subscriptions
Requires the webhooks:write scope (write implies read, so it also satisfies the webhooks:read check every /api-webhook-subscriptions request runs first). Implements the Zapier REST Hooks subscribe contract.
Request body
Body
| Name | Type | Description |
|---|---|---|
target_urlrequired | string (URL) | URL that will receive POST deliveries. Must be a valid absolute URL. |
event_typesrequired | string[] | Non‑empty array of event types to subscribe to. See Event types. |
description | string | Optional human‑readable label shown in the dashboard. |
Valid event_types values: contact.created, contact.updated, contact.tag_added, contact.enriched, contact.note_added, deal.created, deal.updated.
Example request
bash
curl -X POST \
'https://api.wundertreos.com/functions/v1/api-webhook-subscriptions' \
-H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
-H 'Content-Type: application/json' \
-d '{
"target_url": "https://example.com/wundertre/webhook",
"event_types": ["contact.created", "contact.tag_added"],
"description": "Sync new leads to internal CRM"
}'Response
Returns 201 Created with the subscription, including the secret used to sign deliveries:
json
{
"data": {
"id": "a1b2c3d4-1111-2222-3333-444455556666",
"target_url": "https://example.com/wundertre/webhook",
"event_types": ["contact.created", "contact.tag_added"],
"secret": "8f3c2a1d9e7b4f6a5c2d1e0f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b",
"enabled": true,
"description": "Sync new leads to internal CRM",
"created_at": "2026-05-17T14:30:00Z"
}
}Store the secret immediately
The secret is only returned on creation. WundertreOS does not expose it on subsequent list or get calls. Save it in your integration's config before the response is discarded — see Verify signatures.
Errors
| Status | error | When |
|---|---|---|
| 400 | invalid_request | target_url missing or not a URL; event_types empty; an event type is not in the supported set. |
| 403 | forbidden | Credential lacks webhooks:read or webhooks:write. |