wyro

Webhooks

Set a URL with PUT https://wyroapi.com/v1/webhooks {"url": "https://…"}. The response carries the signing secret (shown once). Partners can also set one URL for all their clients in the developer panel.

Events

Event When
post.published A real post went out on every network.
post.partial It went out on some networks and failed on others.
post.failed It failed on every network (error per network).
account.connected A real account was connected.
account.disconnected An account was disconnected.

Each delivery is a POST with JSON { id, type, created_at, workspace_id, external_id, data }.

Headers

Header Value
X-Wyro-Signature Hex HMAC-SHA256 of ${X-Wyro-Timestamp}.${raw body}, keyed by your secret.
X-Wyro-Timestamp Unix seconds of this attempt. Reject it if it is more than 5 minutes old.
X-Wyro-Attempt 1 for the first attempt, 2 to 8 for retries.
X-Wyro-Event-Id The event's id (same as in the body).

Delivery contract

  • First attempt right after the event. Each attempt waits 5 s at most; only a 2xx counts as delivered (redirects are not followed).
  • Retries after 1 min, 5 min, 30 min, 2 h, 6 h, 12 h, 24 h: 8 attempts over about 45 hours. Then the delivery is marked failed.
  • Same id in every attempt. Retries can reach you after a success we did not see (e.g. your 2xx timed out): dedupe on id. Events can arrive out of order; use created_at and GET /v1/posts/{id} for the current state.
  • Disabling. If an endpoint keeps failing for 3 days (no 2xx in between), it is disabled and gets no more events. GET /v1/webhooks shows "status": "disabled" and disabled_at (partners see it in the developer panel). Fix the endpoint and set the URL again (PUT /v1/webhooks, or save it in the panel) to turn it back on.

Answer 2xx fast and do the work afterwards (a queue), so slow work does not time out.

Verify the signature

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

// raw = the request body exactly as received (not re-serialized)
function verify(secret, timestamp, raw, signature) {
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;
  const expected = createHmac("sha256", secret).update(`${timestamp}.${raw}`).digest("hex");
  return expected.length === signature.length && timingSafeEqual(Buffer.from(expected), Buffer.from(signature));
}

The SDKs include it: verifySignature(secret, timestamp, body, signature) (SDKs).