API reference
Events
Facts your services publish once and Halyard fans out to queues and webhook endpoints.
Overview
An event records that something happened, such as order.paid. You publish it once; Halyard delivers it to every queue subscription and webhook endpoint that listens for its type, and retries each delivery on its own.
Events are immutable and kept for 30 days. Halyard also publishes its own events, like job.failed, with the same shape.
- Endpoints
- 3
- ID prefix
- evt_
- Attributes
- 9
The event object
Every event 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 evt_.
objectstringAlways event.
typestringDot-separated name, such as order.paid. Lowercase letters, digits, . and _.
dataobjectThe event's JSON body, up to 64 KB.
sourcestring | nullWhich of your services published it.
occurred_attimestampWhen it happened, as reported by the publisher. Defaults to created_at.
deliveriesobjectDelivery counts across subscribers.
Show 4 child attributesHide child attributes
totalintegerSubscribers that matched the event type.
succeededintegerDeliveries acknowledged.
failedintegerDeliveries that ran out of retries.
pendingintegerDeliveries still in flight or waiting to retry.
created_attimestampWhen the object was created, in ISO 8601 UTC.
livemodebooleantrue for objects created with a live key, false for the test sandbox.
{ "id": "evt_5Gd8Kw1Ry6", "object": "event", "type": "order.paid", "data": { "order_id": "ord_4421", "amount": 4900, "currency": "eur" }, "source": "checkout-service", "occurred_at": "2026-10-14T09:30:15Z", "deliveries": { "total": 3, "succeeded": 2, "failed": 0, "pending": 1 }, "created_at": "2026-10-14T09:30:15Z", "livemode": false}Publish an event
/v3/eventsPublishes an event and starts delivering it to every matching subscriber. The call returns as soon as the event is stored; deliveries happen in the background.
Body parameters
typestringrequiredThe event type, such as order.paid.
dataobjectrequiredJSON body up to 64 KB.
sourcestringName of the publishing service, shown in the dashboard.
occurred_attimestampWhen it happened, if earlier than now.
Returns
The event object. deliveries.pending shows how many subscribers matched.
curl https://api.halyard.example/v3/events \ -H "Authorization: Bearer hy_test_51Hq8Zx2rTmV9cKpL3d" \ -H "Idempotency-Key: ord_4421-paid" \ -H "Content-Type: application/json" \ -d '{ "type": "order.paid", "data": { "order_id": "ord_4421", "amount": 4900, "currency": "eur" }, "source": "checkout-service" }'import { Halyard } from "@halyard/node"; const halyard = new Halyard(process.env.HALYARD_KEY); const event = await halyard.events.publish({ type: "order.paid", data: { order_id: "ord_4421", amount: 4900, currency: "eur" }, source: "checkout-service",}, { idempotencyKey: "ord_4421-paid" });import osfrom halyard import Halyard halyard = Halyard(os.environ["HALYARD_KEY"]) event = halyard.events.publish( type="order.paid", data={ "order_id": "ord_4421", "amount": 4900, "currency": "eur", }, source="checkout-service", idempotency_key="ord_4421-paid",){ "id": "evt_5Gd8Kw1Ry6", "object": "event", "type": "order.paid", "data": { "order_id": "ord_4421", "amount": 4900, "currency": "eur" }, "source": "checkout-service", "occurred_at": "2026-10-14T09:30:15Z", "deliveries": { "total": 3, "succeeded": 0, "failed": 0, "pending": 3 }, "created_at": "2026-10-14T09:30:15Z", "livemode": false}Retrieve an event
/v3/events/{id}Fetches an event with its current delivery counts.
Path parameters
idstringrequiredThe event's ID.
Returns
The event object.
curl https://api.halyard.example/v3/events/evt_5Gd8Kw1Ry6 \ -H "Authorization: Bearer hy_test_51Hq8Zx2rTmV9cKpL3d"import { Halyard } from "@halyard/node"; const halyard = new Halyard(process.env.HALYARD_KEY); const event = await halyard.events.retrieve("evt_5Gd8Kw1Ry6");import osfrom halyard import Halyard halyard = Halyard(os.environ["HALYARD_KEY"]) event = halyard.events.retrieve("evt_5Gd8Kw1Ry6"){ "id": "evt_5Gd8Kw1Ry6", "object": "event", "type": "order.paid", "data": { "order_id": "ord_4421", "amount": 4900, "currency": "eur" }, "source": "checkout-service", "occurred_at": "2026-10-14T09:30:15Z", "deliveries": { "total": 3, "succeeded": 2, "failed": 0, "pending": 1 }, "created_at": "2026-10-14T09:30:15Z", "livemode": false}List events
/v3/eventsLists events from the last 30 days, newest first.
Query parameters
typestringOnly this type. A trailing * matches a prefix, such as order.*.
sourcestringOnly events from this source.
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 event objects in data.
curl -G https://api.halyard.example/v3/events \ -H "Authorization: Bearer hy_test_51Hq8Zx2rTmV9cKpL3d" \ -d type=order.* \ -d limit=2import { Halyard } from "@halyard/node"; const halyard = new Halyard(process.env.HALYARD_KEY); const events = await halyard.events.list({ type: "order.*", limit: 2,});import osfrom halyard import Halyard halyard = Halyard(os.environ["HALYARD_KEY"]) events = halyard.events.list(type="order.*", limit=2){ "object": "list", "url": "/v3/events", "has_more": true, "data": [ { "id": "evt_5Gd8Kw1Ry6", "object": "event", "type": "order.paid", "data": { "order_id": "ord_4421", "amount": 4900, "currency": "eur" }, "source": "checkout-service", "occurred_at": "2026-10-14T09:30:15Z", "deliveries": { "total": 3, "succeeded": 2, "failed": 0, "pending": 1 }, "created_at": "2026-10-14T09:30:15Z", "livemode": false }, { "id": "evt_8Ls2Np7Fh4", "object": "event", "type": "order.created", "data": { "order_id": "ord_4421", "items": 2 }, "source": "checkout-service", "occurred_at": "2026-10-14T09:28:51Z", "deliveries": { "total": 1, "succeeded": 1, "failed": 0, "pending": 0 }, "created_at": "2026-10-14T09:28:51Z", "livemode": false } ]}