Destinations

The destination object

{
  "id": "01m3m5c2yb7h4s1k9q8r6t3v0w",
  "projectId": "01k5ztq3jb9y2a1m9v2xw8e0ha",
  "name": "Orders service",
  "url": "https://orders.example.com/webhooks/payments",
  "urlSecret": false,
  "method": "",
  "state": "enabled",
  "auth": { "kind": "bearer" },
  "rateLimit": { "count": 10, "period": "second" },
  "maxAttempts": 8,
  "timeoutSeconds": 20,
  "failing": false,
  "failuresInRow": 0,
  "failingSince": null,
  "createdAt": "2026-10-01T08:32:00Z",
  "updatedAt": "2026-10-01T08:32:00Z"
}

Fields you send

namestringRequired

1 to 100 characters, on one line. Unique among the project’s destinations, ignoring case.

urlstringRequired

An https URL of at most 2,048 characters, without a user name, password, or # part. Addresses on private networks are refused when we send. When urlSecret is true, leave it empty to keep the address you set before.

urlSecretboolean

Hide the address when the destination is read, such as when it holds a token. false by default.

methodstring

POST, PUT, or PATCH. Empty, the default, sends each webhook with the method it was received with.

statestring

enabled, the default, or paused. Deliveries for a paused destination wait until it is enabled.

auth.kindstring

none, the default, bearer, basic, or header. See Authentication.

auth.tokenstring

For bearer: the token, at most 4,096 characters, on one line.

auth.usernamestring

For basic: the user name, at most 1,024 characters, without colons.

auth.passwordstring

For basic: the password, at most 1,024 characters.

auth.headerstring

For header: the header’s name. It cannot be Host, Content-Type, Content-Length, User-Agent, a webhook- signing header, any header starting with X-Hooks-, or another header we set.

auth.valuestring

For header: the header’s value, at most 4,096 characters, on one line.

rateLimit.countinteger

The most attempts in one period, 1 to 100,000. Leave rateLimit out, or set it to null, for no limit.

rateLimit.periodstring

second, minute, the default, or hour.

maxAttemptsinteger

How many attempts a delivery gets before it is failed, 1 to 20. 6 when you leave it out.

timeoutSecondsinteger

How long each attempt waits for your app to answer, 1 to 60 seconds. 30 when you leave it out.

Fields we add

idstring

The destination’s ID.

projectIdstring

The project the destination belongs to.

urlstring or null

The address, or null when urlSecret is true.

authobject

Only kind, and header for the header kind. Credentials are never shown.

failingboolean

true after 3 failed attempts in a row. A successful attempt clears it.

failuresInRowinteger

How many attempts in a row have failed.

failingSincestring or null

When it started failing.

createdAtstring

When the destination was created.

updatedAtstring

When the destination was last changed.

List destinations

Returns the project’s destinations, newest first, a page at a time. See Paging.

Create a destination

Send its fields. Returns 201 with the new destination, which gets its own signing secret. A name already used gets 409 with the code hooks_name_taken, and a project that holds 100 destinations gets 403 with the code hooks_limit_reached.

Read a destination

Replace a destination

Send every field, as when you create one. A field you leave out goes back to its default. Leave auth out to keep the credentials you set before.

Delete a destination

Deletes the destination, its connections, and its deliveries. Returns 204. This cannot be undone.

Read the signing secret

Returns { "secret": "whsec_…" }. Needs the Edit and resend permission. See Verify deliveries to your app.

Reset the signing secret

Gives the destination a new signing secret, and returns it. Every attempt from then on is signed with it.