API reference
Webhook endpoints
HTTPS URLs that receive signed events from Halyard as they happen.
Overview
A webhook endpoint is an HTTPS URL that receives events as signed POST requests. Each delivery carries a Halyard-Signature header made with the endpoint's secret; see Webhooks for how to verify it.
The secret is only returned when you create an endpoint or rotate its secret. Store it then, the same way you store an API key.
- Endpoints
- 4
- ID prefix
- whk_
- Attributes
- 10
The webhook endpoint object
Every webhook endpoint endpoint returns this object, or a list of them. Attributes marked null are always present in the response, so you can rely on the shape.
Attributes
idstringUnique identifier, prefixed with whk_.
objectstringAlways webhook_endpoint.
urlstringThe HTTPS URL deliveries are sent to.
descriptionstring | nullA note for your team.
enabled_eventsstring[]Event types to deliver. * subscribes to everything, job.* to a prefix.
statusenumenabled, or disabled after 72 hours of failed deliveries.
api_versionstringVersion used to render event payloads for this endpoint.
secretstringSigning secret, prefixed with whsec_. Only present on create and rotate.
created_attimestampWhen the object was created, in ISO 8601 UTC.
livemodebooleantrue for objects created with a live key, false for the test sandbox.
{ "id": "whk_9Tc3Vr5Jd1", "object": "webhook_endpoint", "url": "https://hooks.larkspur.example/halyard", "description": "Job failures for the ops dashboard", "enabled_events": [ "job.failed", "job.succeeded", "schedule.paused" ], "status": "enabled", "api_version": "2026-09-15", "created_at": "2026-08-21T16:45:09Z", "livemode": false}Create a webhook endpoint
/v3/webhook_endpointsRegisters a URL and starts delivering matching events to it. Halyard sends a ping event first to check the URL responds with a 2xx.
Body parameters
urlstringrequiredHTTPS URL, up to 2,048 characters.
enabled_eventsstring[]requiredEvent types or patterns, such as job.failed or job.*.
descriptionstringA note for your team.
api_versionstringDefaults to your account's version, currently 2026-09-15.
Returns
The webhook endpoint object, including its secret.
curl https://api.halyard.example/v3/webhook_endpoints \ -H "Authorization: Bearer hy_test_51Hq8Zx2rTmV9cKpL3d" \ -H "Content-Type: application/json" \ -d '{ "url": "https://hooks.larkspur.example/halyard", "enabled_events": [ "job.failed", "job.succeeded", "schedule.paused" ], "description": "Job failures for the ops dashboard" }'import { Halyard } from "@halyard/node"; const halyard = new Halyard(process.env.HALYARD_KEY); const endpoint = await halyard.webhookEndpoints.create({ url: "https://hooks.larkspur.example/halyard", enabled_events: ["job.failed", "job.succeeded", "schedule.paused"], description: "Job failures for the ops dashboard",});import osfrom halyard import Halyard halyard = Halyard(os.environ["HALYARD_KEY"]) endpoint = halyard.webhook_endpoints.create( url="https://hooks.larkspur.example/halyard", enabled_events=["job.failed", "job.succeeded", "schedule.paused"], description="Job failures for the ops dashboard",){ "id": "whk_9Tc3Vr5Jd1", "object": "webhook_endpoint", "url": "https://hooks.larkspur.example/halyard", "description": "Job failures for the ops dashboard", "enabled_events": [ "job.failed", "job.succeeded", "schedule.paused" ], "status": "enabled", "api_version": "2026-09-15", "created_at": "2026-08-21T16:45:09Z", "livemode": false, "secret": "whsec_Lq8Rt2Vx6Zb4Nc9Pd3Kf"}List webhook endpoints
/v3/webhook_endpointsLists your webhook endpoints, newest first. Secrets are never included.
Query parameters
limitintegerdefault: 20How many objects to return, between 1 and 100.
starting_afterstringA cursor: the ID of the last object on the previous page. The next page starts right after it.
ending_beforestringA cursor for paging backwards: the ID of the first object on the current page.
Returns
A list object with webhook endpoint objects in data.
curl -G https://api.halyard.example/v3/webhook_endpoints \ -H "Authorization: Bearer hy_test_51Hq8Zx2rTmV9cKpL3d" \ -d limit=10import { Halyard } from "@halyard/node"; const halyard = new Halyard(process.env.HALYARD_KEY); const endpoints = await halyard.webhookEndpoints.list({ limit: 10,});import osfrom halyard import Halyard halyard = Halyard(os.environ["HALYARD_KEY"]) endpoints = halyard.webhook_endpoints.list(limit=10){ "object": "list", "url": "/v3/webhook_endpoints", "has_more": false, "data": [ { "id": "whk_9Tc3Vr5Jd1", "object": "webhook_endpoint", "url": "https://hooks.larkspur.example/halyard", "description": "Job failures for the ops dashboard", "enabled_events": [ "job.failed", "job.succeeded", "schedule.paused" ], "status": "enabled", "api_version": "2026-09-15", "created_at": "2026-08-21T16:45:09Z", "livemode": false }, { "id": "whk_3Hf8Mz1Qw6", "object": "webhook_endpoint", "url": "https://api.larkspur.example/hooks/orders", "description": "Order events for fulfilment", "enabled_events": [ "order.*" ], "status": "enabled", "api_version": "2026-09-15", "created_at": "2026-06-03T08:12:30Z", "livemode": false } ]}Delete a webhook endpoint
/v3/webhook_endpoints/{id}Deletes an endpoint. Deliveries in flight are dropped and no new events are sent to it.
Path parameters
idstringrequiredThe webhook endpoint's ID.
Returns
An object with the endpoint's id and deleted: true.
curl -X DELETE https://api.halyard.example/v3/webhook_endpoints/whk_9Tc3Vr5Jd1 \ -H "Authorization: Bearer hy_test_51Hq8Zx2rTmV9cKpL3d"import { Halyard } from "@halyard/node"; const halyard = new Halyard(process.env.HALYARD_KEY); const deleted = await halyard.webhookEndpoints.delete("whk_9Tc3Vr5Jd1");import osfrom halyard import Halyard halyard = Halyard(os.environ["HALYARD_KEY"]) deleted = halyard.webhook_endpoints.delete("whk_9Tc3Vr5Jd1"){ "id": "whk_9Tc3Vr5Jd1", "object": "webhook_endpoint", "deleted": true}Rotate a webhook secret
/v3/webhook_endpoints/{id}/rotate_secretIssues a new signing secret. During the overlap window, deliveries are signed with both secrets so you can deploy the new one without dropping events.
Path parameters
idstringrequiredThe webhook endpoint's ID.
Body parameters
expire_previous_indurationdefault: 24hHow long the old secret keeps signing. Up to 7d; 0s expires it now.
Returns
The webhook endpoint object with the new secret.
curl https://api.halyard.example/v3/webhook_endpoints/whk_9Tc3Vr5Jd1/rotate_secret \ -H "Authorization: Bearer hy_test_51Hq8Zx2rTmV9cKpL3d" \ -H "Content-Type: application/json" \ -d '{ "expire_previous_in": "24h" }'import { Halyard } from "@halyard/node"; const halyard = new Halyard(process.env.HALYARD_KEY); const endpoint = await halyard.webhookEndpoints.rotateSecret("whk_9Tc3Vr5Jd1", { expire_previous_in: "24h",});import osfrom halyard import Halyard halyard = Halyard(os.environ["HALYARD_KEY"]) endpoint = halyard.webhook_endpoints.rotate_secret( "whk_9Tc3Vr5Jd1", expire_previous_in="24h",){ "id": "whk_9Tc3Vr5Jd1", "object": "webhook_endpoint", "url": "https://hooks.larkspur.example/halyard", "description": "Job failures for the ops dashboard", "enabled_events": [ "job.failed", "job.succeeded", "schedule.paused" ], "status": "enabled", "api_version": "2026-09-15", "created_at": "2026-08-21T16:45:09Z", "livemode": false, "secret": "whsec_Yt5Gm1Ws7Jx2Hq8Ln4Cv"}