Webhooks
On this page
With a signing secret, the package registers a route that receives Quiet Social notifications, verifies each one, keeps the status of your posts up to date and raises the matching Laravel events.
The route
Set QUIET_SOCIAL_WEBHOOK_SECRET and the package registers POST /social/webhook (the webhook_path key), named social.webhook. Without a secret, the route does not exist: a route that accepted unsigned bodies would let anyone make up the state of your publications. It sits outside the web middleware group: no session, no CSRF token.
Declare its address in the Quiet Social panel, on the Webhooks page: an https address reachable from the internet, with the events you want. The secret (whsec_…) is shown only once, when the webhook is declared. The steps are described in the guide, and the content of each notification in the webhook reference.
The signature
Every request is verified by the SDK on the raw body, within the tolerance of webhook_tolerance seconds (300 by default). A missing, wrong or expired signature answers 401, and nothing is trusted. Too wide, the tolerance lets an intercepted call be replayed; too narrow, it breaks as soon as a clock drifts.
Duplicates
- Retries. A retry of the API, signed again with a new timestamp, is recognised by its
X-Social-Delivery, its event and its body forwebhook_replay_windowseconds. The default 12 hours cover the whole retry schedule of the API (6 attempts, over about 8 h 36). - Replay. The same signed request, replayed under another delivery identifier, is recognised by its signature for twice the tolerance.
- Failed handling. A delivery whose handling throws an exception is forgotten, so that the next retry goes through.
These deliveries live in your default cache store, which must be shared by every web server: otherwise, one server does not recognise what another has already handled.
Order and statuses
- The link of the publication is updated before the event is raised.
- A status that is not final never replaces a final one, except a failed publication retried from the panel, which reopens its link.
- A notification that arrives before the link of a post just created is kept for a few minutes, and applied as soon as the link is written.
- A publication cancelled or failed in Quiet Social closes the automatic link that was following it.
Answers
Every signed notification is acknowledged with 204, including:
- events the package does not relay (
publication.scheduled,publication.processing…), which still update the link of their publication; - an event that contradicts the status of its signed body (
publication.failedon a published publication), which is logged and raises nothing.
An error would make the API retry, then suspend the endpoint after repeated failures.