Webhooks

Webhooks push job events to your HTTPS endpoint. Every delivery is signed; see the webhooks guide for verification.

API referenceBase URL https://api.sextant.example/v24 endpoints

The Webhook object

idstring

Unique id, prefixed whk_.

urlstring

HTTPS endpoint.

eventsarray

Subscribed events, for example job.failed.

enabledboolean

Disabled endpoints receive nothing.

Create a webhook

POST/webhooks

Registers an endpoint. The response contains the signing secret once; store it, it is never shown again.

Required scope webhooks:write

Request body

urlstring required

HTTPS URL that accepts POST.

eventsarray required

Event names. * subscribes to everything.

enabledboolean optional default true

Start enabled.

Request

cURLShell

curl -X POST https://api.sextant.example/v2/webhooks \
  -H "Authorization: Bearer $SEXTANT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://hooks.example.com/sextant","events":["job.failed","job.dead"]}'

NodeTypeScript

const result = await sextant.webhooks.create({
  url: 'https://hooks.example.com/sextant',
  events: ['job.failed', 'job.dead'],
});

PythonPython

result = client.webhooks.create(
    url="https://hooks.example.com/sextant",
    events=["job.failed", "job.dead"],
)

GoGo

result, err := client.Webhooks.Create(ctx, &sextant.WebhookCreateParams{
	Url: "https://hooks.example.com/sextant",
	Events: []any{"job.failed", "job.dead"},
})
if err != nil {
	return err
}

Responses

The webhook and its secret.

201JSON

{
  "id": "whk_5d02ab",
  "url": "https://hooks.example.com/sextant",
  "events": [
    "job.failed",
    "job.dead"
  ],
  "secret_last4": "9f2c",
  "enabled": true,
  "created_at": "2026-08-11T10:00:00Z",
  "secret": "whsec_3b1d7a09c5e84f6aa21d90e7b4c8f9e2"
}

List webhooks

GET/webhooks

Returns all registered endpoints. Secrets are never included; only the last four characters.

Required scope webhooks:read

Request

cURLShell

curl https://api.sextant.example/v2/webhooks?limit=20 \
  -H "Authorization: Bearer $SEXTANT_TOKEN"

NodeTypeScript

const result = await sextant.webhooks.list({
  limit: 20,
});

PythonPython

result = client.webhooks.list(limit=20)

GoGo

result, err := client.Webhooks.List(ctx, &sextant.ListParams{Limit: 20})
if err != nil {
	return err
}

Responses

All webhooks.

200JSON

{
  "data": [
    {
      "id": "whk_5d02ab",
      "url": "https://hooks.example.com/sextant",
      "events": [
        "job.failed",
        "job.dead"
      ],
      "secret_last4": "9f2c",
      "enabled": true,
      "created_at": "2026-08-11T10:00:00Z"
    }
  ]
}

Send a test event

POST/webhooks/{webhook_id}/test

Delivers a synthetic ping event and returns the result of the attempt.

Required scope webhooks:write

Path parameters

webhook_idstring required

The webhook id.

Request

cURLShell

curl -X POST https://api.sextant.example/v2/webhooks/whk_5d02ab/test \
  -H "Authorization: Bearer $SEXTANT_TOKEN"

NodeTypeScript

const result = await sextant.webhooks.test('whk_5d02ab');

PythonPython

result = client.webhooks.test("whk_5d02ab")

GoGo

result, err := client.Webhooks.Test(ctx, "whk_5d02ab")
if err != nil {
	return err
}

Responses

The delivery result.

200JSON

{
  "delivered": true,
  "status": 204,
  "duration_ms": 182
}

Delete a webhook

DELETE/webhooks/{webhook_id}

Deletes the endpoint. Pending deliveries are dropped.

Required scope webhooks:write

Path parameters

webhook_idstring required

The webhook id.

Request

cURLShell

curl -X DELETE https://api.sextant.example/v2/webhooks/whk_5d02ab \
  -H "Authorization: Bearer $SEXTANT_TOKEN"

NodeTypeScript

await sextant.webhooks.delete('whk_5d02ab');

PythonPython

client.webhooks.delete("whk_5d02ab")

GoGo

if err := client.Webhooks.Delete(ctx, "whk_5d02ab"); err != nil {
	return err
}

Responses

Deleted. No body.

No response body.