API reference

Webhook subscriptions

Manage webhook subscriptions from code: the same subscriptions as in Settings → Developers → Webhooks, with their deliveries. The events themselves — catalog, payloads and signatures — are on Webhooks.

Scopes: webhooks:read · webhooks:write
Plan: Every plan
Guide: Receiving webhooks

The subscription object

A subscription sends the events you choose to one URL, signed with its own secret.

Attributes

iduuidRead-only
Unique identifier of the subscription.
namestring
A name for your own reference.
urlstring
Where Nextora sends events. Must be https:// and may not contain a username or password.
eventsstring[]
The event types to send.
is_activeboolean
Whether events are sent. Nextora sets it to false when it pauses a subscription whose deliveries have failed for three days; set it back to true to resume.
paused_atdate-timeRead-onlyNullable
When Nextora paused the subscription; null when it is not paused. Changing is_active yourself clears it.
paused_reasonenumRead-onlyNullable
failing when Nextora paused the subscription because its deliveries kept failing; null otherwise.
One offailing
failing_sincedate-timeRead-onlyNullable
When the current run of failed attempts began. Cleared by a successful delivery, by resuming, and by a new url. Three days of it pause the subscription.
last_success_atdate-timeRead-onlyNullable
When a delivery last succeeded.
last_failure_atdate-timeRead-onlyNullable
When a delivery attempt last failed.
created_atdate-timeRead-only
When the subscription was created (UTC).
updated_atdate-timeRead-only
When the subscription last changed (UTC).
secretstringRead-only
The signing secret, whsec_…. Returned only when the subscription is created and when the secret is rotated — store it then.

The subscription object

{
  "id": "f3a5c7e9-2b4d-4f6a-8c1e-5d7f9b1a3c60",
  "name": "Deal sync to billing",
  "url": "https://hooks.example.com/nextora",
  "events": [
    "deal.stage_changed",
    "deal.won",
    "deal.lost"
  ],
  "is_active": true,
  "paused_at": null,
  "paused_reason": null,
  "failing_since": "2026-10-10T09:15:03Z",
  "last_success_at": "2026-10-10T08:47:31Z",
  "last_failure_at": "2026-10-10T09:16:04Z",
  "created_at": "2026-10-02T10:30:00Z",
  "updated_at": "2026-10-02T10:30:00Z"
}

The delivery object

One event on its way to one subscription, with the result of its latest attempt. Nextora makes up to six attempts on its own — see retries — and each manual retry adds one more.

Attributes

iduuidRead-only
Unique identifier of the delivery.
eventstring
The event type delivered.
statusenum
success after a 2xx; retrying while automatic attempts remain; failed after the sixth.
One ofpendingretryingsuccessfailed
attemptsinteger
The number of the latest attempt, as sent in Nextora-Attempt. Automatic retries stop at 6; each manual retry adds one, so it can go past 6.
response_codeintegerNullable
The HTTP status your endpoint returned on the last attempt; null when it did not answer within 10 seconds.
next_retry_atdate-timeNullable
When the next attempt is due, while status is retrying.
created_atdate-timeRead-only
When the event was queued for this subscription (UTC).

The delivery object

{
  "id": "d8e0f2a4-6b8c-4d1e-9f3a-7c9e1b3d5f82",
  "event": "deal.stage_changed",
  "status": "retrying",
  "attempts": 2,
  "response_code": 502,
  "next_retry_at": "2026-10-10T09:21:04Z",
  "created_at": "2026-10-10T09:15:02Z"
}

List subscriptions

GET/api/v1/webhooks

Requires webhooks:read

Returns the workspace’s webhook subscriptions. Secrets are never included.

Query parameters

limitinteger
Page size, from 1 to 100.
Default50
cursorstring
The meta.next_cursor of the previous page.

Returns

A list of subscription objects.

GET/api/v1/webhooks

curl https://acme.nextora.co/api/v1/webhooks \
  -H "Authorization: Bearer $NEXTORA_API_KEY"

Response200 OK

{
  "data": [
    {
      "id": "f3a5c7e9-2b4d-4f6a-8c1e-5d7f9b1a3c60",
      "name": "Deal sync to billing",
      "url": "https://hooks.example.com/nextora",
      "events": [
        "deal.stage_changed",
        "deal.won",
        "deal.lost"
      ],
      "is_active": true,
      "paused_at": null,
      "paused_reason": null,
      "failing_since": "2026-10-10T09:15:03Z",
      "last_success_at": "2026-10-10T08:47:31Z",
      "last_failure_at": "2026-10-10T09:16:04Z",
      "created_at": "2026-10-02T10:30:00Z",
      "updated_at": "2026-10-02T10:30:00Z"
    }
  ],
  "meta": {
    "limit": 50,
    "has_more": false,
    "next_cursor": null
  }
}

Create a subscription

POST/api/v1/webhooks

Requires webhooks:write

Creates a subscription and returns its signing secret — the only time you see it, apart from rotation. Store it with your endpoint’s configuration.

Body parameters

namestringRequired
A name for your own reference.
urlstringRequired
Where to send events: an https:// URL without a username or password, on a public host. Addresses that are or resolve to private, loopback, link-local or cloud-metadata ranges are refused with 400 validation_failed.
eventsstring[]Required
Event types to send, from the event catalog — 20 in all.
is_activeboolean
false stops deliveries without deleting the subscription.
Defaulttrue

Returns

The new subscription with secret, and 201 Created.

POST/api/v1/webhooks

curl -X POST https://acme.nextora.co/api/v1/webhooks \
  -H "Authorization: Bearer $NEXTORA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Deal sync to billing",
    "url": "https://hooks.example.com/nextora",
    "events": [
      "deal.stage_changed",
      "deal.won",
      "deal.lost"
    ]
  }'

Response201 Created

{
  "data": {
    "id": "f3a5c7e9-2b4d-4f6a-8c1e-5d7f9b1a3c60",
    "name": "Deal sync to billing",
    "url": "https://hooks.example.com/nextora",
    "events": [
      "deal.stage_changed",
      "deal.won",
      "deal.lost"
    ],
    "is_active": true,
    "paused_at": null,
    "paused_reason": null,
    "failing_since": null,
    "last_success_at": null,
    "last_failure_at": null,
    "created_at": "2026-10-10T09:00:00Z",
    "updated_at": "2026-10-10T09:00:00Z",
    "secret": "whsec_9f3b7c1e5a2d8f4b6c0e3a7d1f5b9c2e8a4d6f0b3c7e1a5d"
  }
}

Retrieve a subscription

GET/api/v1/webhooks/{id}

Requires webhooks:read

Returns one subscription, without its secret.

Path parameters

iduuidRequired
The subscription’s ID.

Returns

The subscription.

GET/api/v1/webhooks/{id}

curl https://acme.nextora.co/api/v1/webhooks/f3a5c7e9-2b4d-4f6a-8c1e-5d7f9b1a3c60 \
  -H "Authorization: Bearer $NEXTORA_API_KEY"

Response200 OK

{
  "data": {
    "id": "f3a5c7e9-2b4d-4f6a-8c1e-5d7f9b1a3c60",
    "name": "Deal sync to billing",
    "url": "https://hooks.example.com/nextora",
    "events": [
      "deal.stage_changed",
      "deal.won",
      "deal.lost"
    ],
    "is_active": true,
    "paused_at": null,
    "paused_reason": null,
    "failing_since": "2026-10-10T09:15:03Z",
    "last_success_at": "2026-10-10T08:47:31Z",
    "last_failure_at": "2026-10-10T09:16:04Z",
    "created_at": "2026-10-02T10:30:00Z",
    "updated_at": "2026-10-02T10:30:00Z"
  }
}

Update a subscription

PATCH/api/v1/webhooks/{id}

Requires webhooks:write

Changes the fields you send. To resume a subscription Nextora paused after three days of failures, send is_active: true: that clears paused_at, paused_reason and failing_since. A new url clears failing_since too. PUT does the same as PATCH.

Path parameters

iduuidRequired
The subscription’s ID.

Body parameters

namestring
A name for your own reference.
urlstring
Where to send events: an https:// URL without a username or password, on a public host. Addresses that are or resolve to private, loopback, link-local or cloud-metadata ranges are refused with 400 validation_failed.
eventsstring[]
Event types to send, from the event catalog — 20 in all.
is_activeboolean
false stops deliveries without deleting the subscription.

Returns

The updated subscription.

PATCH/api/v1/webhooks/{id}

curl -X PATCH https://acme.nextora.co/api/v1/webhooks/f3a5c7e9-2b4d-4f6a-8c1e-5d7f9b1a3c60 \
  -H "Authorization: Bearer $NEXTORA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      "deal.stage_changed",
      "deal.won",
      "deal.lost",
      "deal.created"
    ]
  }'

Response200 OK

{
  "data": {
    "id": "f3a5c7e9-2b4d-4f6a-8c1e-5d7f9b1a3c60",
    "name": "Deal sync to billing",
    "url": "https://hooks.example.com/nextora",
    "events": [
      "deal.stage_changed",
      "deal.won",
      "deal.lost",
      "deal.created"
    ],
    "is_active": true,
    "paused_at": null,
    "paused_reason": null,
    "failing_since": "2026-10-10T09:15:03Z",
    "last_success_at": "2026-10-10T08:47:31Z",
    "last_failure_at": "2026-10-10T09:16:04Z",
    "created_at": "2026-10-02T10:30:00Z",
    "updated_at": "2026-10-10T10:02:44Z"
  }
}

Delete a subscription

DELETE/api/v1/webhooks/{id}

Requires webhooks:write

Deletes the subscription. Nextora stops sending its events.

Path parameters

iduuidRequired
The subscription’s ID.

Returns

{ "data": { "id": "…", "deleted": true } }.

DEL/api/v1/webhooks/{id}

curl -X DELETE https://acme.nextora.co/api/v1/webhooks/f3a5c7e9-2b4d-4f6a-8c1e-5d7f9b1a3c60 \
  -H "Authorization: Bearer $NEXTORA_API_KEY"

Response200 OK

{
  "data": {
    "id": "f3a5c7e9-2b4d-4f6a-8c1e-5d7f9b1a3c60",
    "deleted": true
  }
}

Rotate the signing secret

POST/api/v1/webhooks/{id}/rotate-secret

Requires webhooks:write

Replaces the signing secret and returns the new one, once. The old secret stops working at once — there is no overlap window: every later delivery carries a single v1 signature made with the new secret. Deploy it to your endpoint straight away; deliveries your endpoint rejects meanwhile are retried.

Path parameters

iduuidRequired
The subscription’s ID.

Returns

The subscription with its new secret.

POST/api/v1/webhooks/{id}/rotate-secret

curl -X POST https://acme.nextora.co/api/v1/webhooks/f3a5c7e9-2b4d-4f6a-8c1e-5d7f9b1a3c60/rotate-secret \
  -H "Authorization: Bearer $NEXTORA_API_KEY"

Response200 OK

{
  "data": {
    "id": "f3a5c7e9-2b4d-4f6a-8c1e-5d7f9b1a3c60",
    "name": "Deal sync to billing",
    "url": "https://hooks.example.com/nextora",
    "events": [
      "deal.stage_changed",
      "deal.won",
      "deal.lost"
    ],
    "is_active": true,
    "paused_at": null,
    "paused_reason": null,
    "failing_since": "2026-10-10T09:15:03Z",
    "last_success_at": "2026-10-10T08:47:31Z",
    "last_failure_at": "2026-10-10T09:16:04Z",
    "created_at": "2026-10-02T10:30:00Z",
    "updated_at": "2026-10-10T10:05:18Z",
    "secret": "whsec_2e8a4d6f0b3c7e1a5d9f3b7c1e5a2d8f4b6c0e3a7d1f5b9c"
  }
}

Send a test event

POST/api/v1/webhooks/{id}/test

Requires webhooks:write

Sends a webhook.test event to the subscription’s URL now — signed, with the same headers as a real event — and returns the delivery, so you can check your endpoint end to end.

Path parameters

iduuidRequired
The subscription’s ID.

Returns

The delivery of the test event.

POST/api/v1/webhooks/{id}/test

curl -X POST https://acme.nextora.co/api/v1/webhooks/f3a5c7e9-2b4d-4f6a-8c1e-5d7f9b1a3c60/test \
  -H "Authorization: Bearer $NEXTORA_API_KEY"

Response200 OK

{
  "data": {
    "id": "a4c6e8f0-2b4d-4f6a-8c0e-2d4f6b8a0c19",
    "event": "webhook.test",
    "status": "success",
    "attempts": 1,
    "response_code": 200,
    "next_retry_at": null,
    "created_at": "2026-10-10T09:02:11Z"
  }
}

List deliveries

GET/api/v1/webhooks/{id}/deliveries

Requires webhooks:read

Returns a subscription’s deliveries, newest first: what was sent, whether it arrived, and when the next retry is due.

Path parameters

iduuidRequired
The subscription’s ID.

Query parameters

limitinteger
Page size, from 1 to 100.
Default50
cursorstring
The meta.next_cursor of the previous page.

Returns

A list of delivery objects.

GET/api/v1/webhooks/{id}/deliveries

curl https://acme.nextora.co/api/v1/webhooks/f3a5c7e9-2b4d-4f6a-8c1e-5d7f9b1a3c60/deliveries \
  -H "Authorization: Bearer $NEXTORA_API_KEY"

Response200 OK

{
  "data": [
    {
      "id": "d8e0f2a4-6b8c-4d1e-9f3a-7c9e1b3d5f82",
      "event": "deal.stage_changed",
      "status": "retrying",
      "attempts": 2,
      "response_code": 502,
      "next_retry_at": "2026-10-10T09:21:04Z",
      "created_at": "2026-10-10T09:15:02Z"
    },
    {
      "id": "c6e8a0b2-4d6f-4a8c-9e2b-6f8a0c2e4b31",
      "event": "deal.won",
      "status": "failed",
      "attempts": 6,
      "response_code": 500,
      "next_retry_at": null,
      "created_at": "2026-10-08T17:30:45Z"
    }
  ],
  "meta": {
    "limit": 50,
    "has_more": false,
    "next_cursor": null
  }
}

Retry a delivery

POST/api/v1/webhooks/deliveries/{id}/retry

Requires webhooks:write

Sends a delivery again now — a failed one after you fixed your endpoint, or a retrying one without waiting for its next attempt. The retry is the delivery’s next attempt: attempts and Nextora-Attempt go up by one, so a delivery that failed after six attempts is retried as attempt 7.

Path parameters

iduuidRequired
The delivery’s ID.

Returns

The delivery, with the result of this attempt.

POST/api/v1/webhooks/deliveries/{id}/retry

curl -X POST https://acme.nextora.co/api/v1/webhooks/deliveries/c6e8a0b2-4d6f-4a8c-9e2b-6f8a0c2e4b31/retry \
  -H "Authorization: Bearer $NEXTORA_API_KEY"

Response200 OK

{
  "data": {
    "id": "c6e8a0b2-4d6f-4a8c-9e2b-6f8a0c2e4b31",
    "event": "deal.won",
    "status": "success",
    "attempts": 7,
    "response_code": 200,
    "next_retry_at": null,
    "created_at": "2026-10-08T17:30:45Z"
  }
}