API Reference
API Reference / Endpoints / Platform

Create a webhook destination

/v1/webhooks

Register an HTTPS endpoint for async completion events.

POST/v1/webhooks
Auth: API keyBilling: FreeBehavior: SyncScopes: webhooks:manage
POSTSyncjsonwebhooks:manage

When to use it

Use this before you rely on event-driven completion. It lets you replace polling with signed callbacks to your own infrastructure.

Behavior on success

Returns a completed payload on the normal success path.

Integration shape

Authorization model
webhooks:manage
Request format
json
Polling pattern
No polling required on the normal success path.

Request

FieldTypeRequiredDescription
urlstringYesHTTPS destination that will receive POST deliveries.
eventsstring[]YesNon-empty array of event names or `*` for all supported events.
descriptionstringOptionalOptional dashboard-facing description up to 500 characters.

Example request

POST /v1/webhooks
const response = await fetch('https://prod-backup-backend.wubble.ai/v1/webhooks', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.WUBBLE_API_KEY}`,
    'Idempotency-Key': crypto.randomUUID(),
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "url": "https://example.com/api/wubble/webhooks",
  "events": [
    "music.instrumental.completed",
    "sound_effects.generated"
  ],
  "description": "Primary production receiver"
}),
});

const payload = await response.json();
console.log(payload);

Example response

Response shapejson
{
  "success": true,
  "data": {
    "webhook_id": "wh_123",
    "url": "https://example.com/api/wubble/webhooks",
    "events": [
      "music.instrumental.completed",
      "sound_effects.generated"
    ],
    "description": "Primary production receiver",
    "secret": "whsec_please_store_this_once",
    "is_active": true,
    "created_at": "2026-05-12T12:00:00.000Z"
  }
}

Implementation notes

Only HTTPS destinations are allowed.
The backend applies SSRF protection and rejects unsafe targets such as localhost or private network addresses.

Production guidance

Pair this route with idempotency on POST requests and either request polling or webhooks whenever the response is asynchronous.
Was this page helpful?
Previous
List webhooksNext