Webhooks

When a post is scheduled, published or fails, when a channel needs reconnecting or a schedule asks for new posts, something usually has to happen next: log it, tell the team, publish through your own tool. A webhook tells your automation about it. Staqly sends a signed JSON request to your URL for every event you subscribe to, and keeps retrying until your endpoint answers with a 2xx.

Webhook, alert or poll?Copy Anchor Link

How webhooks workCopy Anchor Link

1. Something happens in staqly, such as a post being published. Staqly records an event.
2. For every active webhook whose events and collection_ids match, staqly queues a delivery.
3. A background worker sends the delivery as a POST with a JSON body and an X-Staqly-Signature header.
4. Your endpoint verifies the signature, does its work and answers 2xx. Anything else is retried.

Setting up a webhookCopy Anchor Link

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",
  "description": "Publishing log",
  "events": ["post.published", "post.failed"]
}'

curl -s -H "Authorization: Bearer $STAQLY_API_KEY" -X POST http://localhost:3333/v1/webhooks/wh_lv5rc7rttjnfwnnsn4ny/test

Webhook settingsCopy Anchor Link

Change any field with PATCH /v1/webhooks/{id}; delete a webhook with DELETE /v1/webhooks/{id}. See Event types for everything you can subscribe to.

Plan limits (cloud): 3 webhooks on Starter, 10 on Plus, unlimited on Pro and Business. Over the limit, creating a webhook returns 402 plan_limit_exceeded with details.limit = "webhooks". See Plans.

The requestCopy Anchor Link

POST <your url>
Content-Type: application/json
User-Agent: Staqly-Webhooks/1.0
X-Staqly-Event: post.published
X-Staqly-Event-Id: evt_looiyqe5kfkjh4xedcnd          # stable per event: deduplicate on this
X-Staqly-Delivery: dlv_bgx4s2p4xnzimajdkoki          # stable across retries of one delivery
X-Staqly-Timestamp: 1791800000    # unix seconds, when this attempt was signed
X-Staqly-Signature: sha256=<hex HMAC-SHA256(secret, timestamp + "." + raw body)>

{
  "id": "evt_looiyqe5kfkjh4xedcnd",
  "type": "post.published",
  "created_at": "2026-10-20T07:00:04.000000Z",
  "workspace_id": "ws_4uvnnzgy5vvpo4hnqnco",
  "delivery_id": "dlv_bgx4s2p4xnzimajdkoki",
  "attempt": 1,
  "actor": { "type": "system", "id": "publisher", "name": "Publisher" },
  "data": {
    "post": {
      "id": "post_oalirbz67y4m4cqxq5dw", "status": "published", "content": "v1.4 is out.",
      "publish_at": "2026-10-20T07:00:00Z", "published_at": "2026-10-20T07:00:04Z",
      "targets": [ { "channel_id": "ch_7h2kq9xw3nbvd5yhzm6a", "channel_name": "Brand on X", "provider": "x", "status": "published", "external_url": "https://x.com/brand/status/1790000000000000042" } ]
    },
    "collection": { "id": "col_qjuybkx6355nz4no6pqk", "name": "Product updates" }
  }
}

• The payload is built from the event snapshot taken when the change happened, not the post's current state.
• actor.type is local, session, api_key or system (the scheduler, the publisher).
• post.publish_requested adds channel, target and timeout_seconds for your own automation.
• Media URLs inside data.post.media_items[].url use PUBLIC_API_URL and require authentication.

Verifying signaturesCopy Anchor Link

Compute HMAC-SHA256(secret, "<X-Staqly-Timestamp>.<raw body>"), hex-encode it, prefix sha256= and compare it in constant time with X-Staqly-Signature. Use the raw request body: re-serialized JSON will not match. Rejecting timestamps older than a few minutes protects against replays.

import { createHmac, timingSafeEqual } from 'node:crypto';

export function verifyStaqly(secret: string, rawBody: string, headers: Record<string, string | undefined>) {
  const ts = headers['x-staqly-timestamp'] ?? '';
  const sig = headers['x-staqly-signature'] ?? '';
  if (!ts || Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false;
  const expected = 'sha256=' + createHmac('sha256', secret).update(`${ts}.${rawBody}`).digest('hex');
  return sig.length === expected.length && timingSafeEqual(Buffer.from(sig), Buffer.from(expected));
}

The SDK also exports isValidWebhook(secret, rawBody, headers), which returns true or false instead of throwing.

Delivery guaranteesCopy Anchor Link

Delivery is at-least-once and not ordered:

• The event and its delivery rows are written in the same database transaction as the change (a transactional outbox). If the change commits, the delivery exists.
• A background worker sends deliveries outside any transaction, several in parallel (see Retries). It leases each one for 2 minutes before sending; if the process dies mid-send, the delivery is sent again when the lease runs out. Pending deliveries survive restarts.
• So a receiver can see the same event twice. Deduplicate on X-Staqly-Event-Id (or the body's id) when a side effect must not repeat.
• And events can arrive out of order: parallel deliveries and retries mean a later event (say post.published) can arrive before an earlier one of the same post (post.scheduled). Order by the body's created_at (when the change happened, not when it was sent) and ignore an event older than the last one you handled for that post. The webhook body has no sequence number; when you need every event in exact order, read GET /v1/events, whose seq grows with every event, for example with the webhook only as the trigger.

RetriesCopy Anchor Link

A delivery succeeds on any 2xx response. Anything else (non-2xx, timeout, connection error) is retried with exponential backoff:

The worker sends at most 4 requests at a time overall and 2 per workspace. A workspace whose receivers are slow is skipped (its deliveries stay due) instead of holding up everyone else.

When a receiver keeps failingCopy Anchor Link

After 5 failed attempts in a row to one webhook (any delivery: an error, a timeout or a non-2xx answer), its circuit breaker opens: the webhook's due deliveries wait instead of being sent, for the backoff of the failures past the fifth (up to WEBHOOK_RETRY_MAX). Waiting counts no attempt, so nothing is given up because of it. Then one round goes through again; the first success closes the breaker. The count is kept in the server's memory, so a restart starts it afresh.

Delivery history and testingCopy Anchor Link

The delivery history keeps the status, attempts, the last status code, the error and the first 2 KB of the last response. In cloud mode it keeps only the status code and a short reason, never the response body.

The test endpoint is rate-limited per API key or session (burst 5, then 10 per minute; 429). The CLI has the same commands: staqly webhooks deliveries, staqly webhooks retry and staqly webhooks test.

Network policy (SSRF guard)Copy Anchor Link

Webhook URLs are user input, so the worker restricts where it connects:

• Always blocked: link-local addresses (including the 169.254.169.254 cloud metadata endpoint), multicast, unspecified and reserved ranges. IPv6 forms that embed an IPv4 address (NAT64, 6to4) are checked as that IPv4 address.
• Private addresses (LAN, Docker networks such as http://n8n:5678; 100.64.0.0/10 counts as private) are allowed by default in Staqly Community Edition only (WEBHOOK_ALLOW_PRIVATE, default true in local and false in cloud mode).
• Loopback (127.0.0.1) is blocked by default. Enable it with WEBHOOK_ALLOW_LOOPBACK=true only when the API runs outside Docker and the receiver listens on localhost. Inside Docker, localhost is the staqly container itself: use host.docker.internal or the receiver's container name on a shared Docker network.
• The check runs on the resolved IP at connect time, so DNS rebinding cannot sneak past it. Redirects are not followed and no proxy is taken from the environment.

A blocked target shows up in the delivery's last_error, for example private destination 192.168.1.20 is not allowed (set WEBHOOK_ALLOW_PRIVATE=true).

Next stepsCopy Anchor Link