Create a webhook

POST

/api/v1/webhooks

Request bodyrequired

urlrequired

string · uri

An https URL that accepts POST requests.

headersoptional

object

Extra headers sent with every request, for example an API key your endpoint checks: {"Authorization": "Bearer ..."}. Up to 5. Names are stored in lower case.

eventTypesoptional

string | string[]

The event types this webhook gets: "all" (every type, also types added later) or a list. Left out, it is "all".

Response

201Webhook created. The response carries the secret.

webhook

object

id	string · uuid
url	string
headerNames	string[] Names of the extra headers sent with every request.
eventTypes	string \| string[] The [event types](https://needle.app/docs/webhooks#event-types) this webhook gets. "all" means every type, also types added later. A list stays as it is: types added later are not sent until you add them.
lastAttemptAt	string · date-time \| null
lastError	string \| null Why the last failed delivery failed, for example 401. Null once a delivery succeeds.
disabledAt	string · date-time \| null When the webhook was turned off because your URL gave no 2xx answer for 3 days. Nothing is sent while it is off; turn it on with enabled: true. Null while it is on.
createdAt	string · date-time
createdBy	string · uuid The member who created the webhook. It receives the events they can see, and is deleted when they leave the workspace.

secret

string

The signing secret, whsec_…. Returned only here, when the webhook is created, and never again.

requestId

string · uuid

Id of this request, for support and troubleshooting

Errors

400: Bad request
401: Unauthorized: missing or invalid API key
403: Forbidden
404: Not found
409: The workspace already has 5 webhooks.
422: Invalid request payload

Request bodyrequired

Response

Errors

Search docs