Needle LogoNeedle

Webhooks

Create a webhook

Every outbound event is sent to each of the organization's webhooks, signed with that webhook's secret. Up to 5 per organization. See [Webhooks](https://needle.app/docs/webhooks) for the request body, headers, signature checks, and retries.

POST

/api/v1/webhooks

Request bodyrequired

urlrequired

string · uri

An https URL that accepts POST requests.

Response

201Webhook created. The response carries the secret.

webhook

object

id

string · uuid

url

string

lastAttemptAt

string · date-time | null

lastError

string | null

Why the last failed delivery failed, for example 401. Null once a delivery succeeds.

createdAt

string · date-time

createdBy

string · uuid | null

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 organization already has 5 webhooks.
  • 422: Invalid request payload

Search docs

Search documentation, API reference, and MCP tools

We use cookies to enhance your experience on Needle and keep your data secure. Privacy Policy