Create webhook subscription
Subscribe a target URL to one or more WundertreOS event types.
POST/api-webhook-subscriptions
Requires both webhooks:read and webhooks:write scopes (every /api-webhook-subscriptions request checks webhooks:read first, then POST additionally checks webhooks:write). 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. |