Event types

Every change in staqly (a post created, scheduled, published or failed, a channel connected, a schedule run) is recorded as an event. The same events feed the activity log, a post's history, webhooks and alerts. Use this page to pick the event types your automation should react to.

Read and subscribe to eventsCopy Anchor Link

curl -s -H "Authorization: Bearer $STAQLY_API_KEY" "http://localhost:3333/v1/events?type=post.published"

curl -s -H "Authorization: Bearer $STAQLY_API_KEY" "http://localhost:3333/v1/events?schedule_id=sch_5k2nq8rx7bvm3dz4hcye"
curl -s -H "Authorization: Bearer $STAQLY_API_KEY" "http://localhost:3333/v1/events?actor_type=api_key&actor_id=key_r7zq2m4xk3pw6ta5ned2&from=2026-10-13&to=2026-10-20"

curl -s -H "Authorization: Bearer $STAQLY_API_KEY" -X POST http://localhost:3333/v1/webhooks -H 'Content-Type: application/json' \
  -d '{"url":"https://example.com/hooks/staqly","events":["post.published","post.failed"]}'

Event shapeCopy Anchor Link

Events are immutable. Each one has these fields:

{
  "id": "evt_looiyqe5kfkjh4xedcnd",
  "seq": 1042,
  "type": "post.target_published",
  "collection_id": "col_qjuybkx6355nz4no6pqk",
  "post_id": "post_oalirbz67y4m4cqxq5dw",
  "channel_id": "ch_7h2kq9xw3nbvd5yhzm6a",
  "schedule_id": null,
  "actor": { "type": "system", "id": "publisher", "name": "Publisher" },
  "data": {
    "post": { "id": "post_oalirbz67y4m4cqxq5dw", "status": "publishing", "content": "v1.4 is out.", "targets": [ { "channel_id": "ch_7h2kq9xw3nbvd5yhzm6a", "status": "published", "external_url": "https://x.com/brand/status/1790000000000000042" } ] },
    "collection": { "id": "col_qjuybkx6355nz4no6pqk", "name": "Product updates" },
    "channel_id": "ch_7h2kq9xw3nbvd5yhzm6a",
    "url": "https://x.com/brand/status/1790000000000000042",
    "external_id": "1790000000000000042",
    "error": ""
  },
  "created_at": "2026-10-20T07:00:04Z"
}

Post events carry a snapshot: data.post (the post after the change, with its targets; before the deletion for post.deleted) and data.collection (id, name). Events about other objects carry them in data (data.channel, data.schedule, data.webhook).

Post eventsCopy Anchor Link

Per-target events also set channel_id, so GET /v1/events?channel_id=... is one channel's publishing history.

Channel and schedule eventsCopy Anchor Link

Other eventsCopy Anchor Link

webhook.* events are recorded in the activity log but are not delivered to webhooks (except webhook.test, which goes only to the webhook being tested), so changing a webhook can't loop back to its receiver.

Audit eventsCopy Anchor Link

The credential events above (api_key.*, session.*, recovery_key.*, access_token.*, device.*, device_link.*, sign_in_method.*) are audit events: GET /v1/events and GET /v1/events/export list them only for admins: dashboard sessions, the Community Edition's access token and keys with the admin scope. Other keys don't see them.

Webhooks and alerts get audit events only when a pattern names their family ("session.*", "api_key.revoked"), never through "*" or another glob, and only an admin may subscribe that way (403 otherwise).

Matching events in webhooksCopy Anchor Link

Webhooks and alerts match events patterns against the type: exact names, "*", or globs such as "post.*" and "post.*_requested". Optionally restrict to collection_ids. See Webhooks.

Patterns are checked when you save a webhook or alert (1 to 50 of them): an exact name must be one of the types on this page (custom events such as post.shipped are rejected), and a glob must stay inside a known family (post., channel., schedule., collection., webhook., alert....). A typo such as post.publised or posts.* is rejected with 422 instead of silently never matching.

ActorsCopy Anchor Link

The actor field says who caused the event. Filter by it with actor_type and actor_id.

System actors:

Next stepsCopy Anchor Link