Skip to content
Quiet Social

Webhooks

This documentation is translated from French. Should the two versions differ, the French version prevails.

A webhook notifies your application when a publication changes state, without it having to poll the API. Quiet Social sends a signed POST request to the URL you register.

Endpoints are registered through the API, with the webhooks:manage scope, or from the dashboard, menu Webhooks (see the guide). Both paths lead to the same endpoint, with the same rules.

Register an endpoint: POST /webhooks

Field Type Required Note
url text (2048) yes Over https, reachable from the internet.
events list yes At least one event from the catalog.
brand_id brd_… no Limits the endpoint to one brand's events. When absent, it covers the whole workspace.
curl -X POST https://quietsocial.dev/api/v1/webhooks \
  -u "$QUIET_CLIENT_ID:$QUIET_CLIENT_SECRET" \
  -H 'Content-Type: application/json' \
  -d '{
        "url": "https://example.com/quiet-social/webhook",
        "events": ["publication.published", "publication_target.failed"]
      }'

201 Created:

{
  "data": {
    "id": "whe_01k4b90a7x1y2z3b4c5d6e7f8g",
    "url": "https://example.com/quiet-social/webhook",
    "events": ["publication.published", "publication_target.failed"],
    "status": "active",
    "failure_count": 0,
    "last_success_at": null,
    "last_failure_at": null,
    "secret": "whsec_…",
    "created_at": "2026-10-01T09:20:15+00:00"
  },
  "reveal_secret": true
}

Store secret now. It is returned only on creation: no later read shows it. Losing it means deleting the endpoint and registering a new one.

The URL is checked as soon as it is registered. The following are refused, as 422 on the url field with the exact reason:

  • any scheme other than https;
  • names reserved for the machine or the local network (localhost, .local, .internal, a name without a dot…);
  • private or reserved addresses, and any name whose DNS resolution leads to such an address.

A client attached to a brand always registers endpoints for its brand. A workspace client that sends brand_id must designate a brand of its workspace; otherwise the registration is refused with 422 on the brand_id field. GET /brands gives the valid identifiers.

Codes: 201, 401, 403, 422, 429.

List: GET /webhooks

The endpoints visible to the client, in order of creation, without pagination. A client attached to a brand sees that brand's endpoints and those that cover the whole workspace. It reads the latter but does not change, delete or test them: those three routes answer 403 with endpoint_shared.

secret does not appear. The health state does: status is active or suspended, failure_count counts consecutive failed deliveries, last_success_at and last_failure_at date the latest outcomes.

Codes: 200, 401, 403, 429.

Update: PATCH /webhooks/{id}

Changes the URL, the list of events, or both. An absent field stays as is. The URL is checked as on registration.

curl -X PATCH https://quietsocial.dev/api/v1/webhooks/whe_01k4b90a7x1y2z3b4c5d6e7f8g \
  -u "$QUIET_CLIENT_ID:$QUIET_CLIENT_SECRET" \
  -H 'Content-Type: application/json' \
  -d '{"events": ["publication.failed", "publication_target.failed"]}'

200 OK, with the endpoint read again, without secret. An endpoint's brand and its status cannot be changed.

Codes: 200, 401, 403, 404, 422, 429.

Delete: DELETE /webhooks/{id}

204 No Content. Deletion is permanent.

Codes: 204, 401, 403, 404, 429.

Test: POST /webhooks/{id}/test

Sends a test notification, through exactly the same path as a real one: same signature, same headers, same retries.

{
  "data": {
    "delivery_id": "whd_01k4b91b8y2z3a4c5d6e7f8g9h",
    "status": "pending"
  }
}

202 Accepted: the delivery is queued, it has not happened yet. Its outcome can be seen on your endpoint, or in last_success_at and last_failure_at.

The event is webhook.test, outside the catalog: your endpoint receives it even if it has not subscribed to it. Do not let it fall into an "unknown event" error branch. Its body:

{
  "message": "This is a check notification sent from Quiet Social.",
  "sent_at": "2026-10-01T09:21:03+00:00"
}

Two refusals:

  • a suspended endpoint receives nothing: 409 endpoint_suspended, « This endpoint is suspended and receives nothing: reactivate it first. »;
  • each test really goes out to your URL: 5 per minute and per endpoint at most, dashboard and API combined. Beyond that, 429 too_many_requests, with Retry-After.

Codes: 202, 401, 403, 404, 409, 429.

Event catalog

Event Emitted when
publication.created A publication is created, from the API or the dashboard.
publication.approved A publication submitted for approval is approved, by the team or by the client.
publication.scheduled A publication changes to scheduled: released by publish, or restarted by retry after it had finished.
publication.processing At least one target has left and another has not yet completed.
publication.published All targets are published.
publication.partially_published All targets have an outcome, and only some are published.
publication.failed All targets have an outcome, and none is published.
publication.cancelled All targets are cancelled.
publication_target.published A target is published.
publication_target.failed A target fails, or changes to requires_reconnect: from your point of view, the delivery will not happen without intervention.
social_connection.requires_reconnect A connection can no longer publish: its access has expired, been revoked, or been refused by the network. Emitted once, at the transition; not on every check while it still needs restoring.
destination.disabled An active destination stops being active: disabled by a team member, or become unavailable.

An endpoint limited to one brand receives only that brand's events. A connection belongs to the workspace and not to a brand: a brand's endpoint learns of social_connection.requires_reconnect only if the connection carries destinations of that brand, and then receives a reduced body (see below).

What your endpoint receives

POST /quiet-social/webhook HTTP/1.1
Content-Type: application/json
X-Social-Event: publication.published
X-Social-Delivery: whd_01k4b91b8y2z3a4c5d6e7f8g9h
X-Social-Timestamp: 1790846463
X-Social-Signature: 6812dcecedae62e31509cc73c4f8c61291eae937dac924bf42273aba9c36a7dc
Header Content
X-Social-Event The name of the event. It is not repeated in the body.
X-Social-Delivery The whd_… identifier of the delivery, the same on every attempt.
X-Social-Timestamp The Unix timestamp of the signature, regenerated on every attempt.
X-Social-Signature HMAC-SHA256(timestamp + "." + raw body, secret), in hexadecimal.

For a publication.* event, the body carries the publication, exactly as GET /publications/{id} returns it:

{
  "publication": {
    "id": "pub_01k4b8y5t2v9h6p8w0y2z4b6c8",
    "status": "published",
    "external_reference": "article-42",
    "targets": ["…"]
  }
}

For a publication_target.* event, it carries the target, exactly as in targets[], and the identifier of its publication:

{
  "target": {
    "destination_id": "dst_01k4b8x2q9r7f3m5t6v8w0y2z4",
    "network": "facebook",
    "provider": "meta",
    "status": "published",
    "external_url": "https://www.facebook.com/…",
    "attempts": 1,
    "error": null
  },
  "publication_id": "pub_01k4b8y5t2v9h6p8w0y2z4b6c8"
}

Both examples are abridged: the fields are all those described in Publications.

For destination.disabled, the body carries the destination, exactly as GET /destinations/{id} returns it:

{
  "destination": {
    "id": "dst_01k4b8x2q9r7f3m5t6v8w0y2z4",
    "network": "facebook",
    "name": "Fabrique du Nord",
    "status": "disabled",
    "can_publish": false,
    "capabilities": {"…": "…"}
  }
}

For social_connection.requires_reconnect, it carries the connection and its destinations:

{
  "social_connection": {
    "provider": "meta",
    "status": "requires_reconnect",
    "error_code": "meta.token_invalid",
    "account": "Camille Martin",
    "error_message": "L'autorisation Meta de ce compte n'est plus valide ; reconnectez-le."
  },
  "destinations": [
    { "id": "dst_01k4b8x2q9r7f3m5t6v8w0y2z4", "network": "facebook", "name": "Fabrique du Nord" }
  ]
}

status is expired, revoked or requires_reconnect. An endpoint limited to one brand receives a reduced body: neither account nor error_message, and only its brand's destinations. The connection has no public identifier; restore it from the dashboard.

Verifying the signature

Verify the signature on the raw body, before any JSON decoding: a body decoded and then re-encoded no longer has the same bytes. Refuse a timestamp that is too old — five minutes is a good window — so that an intercepted request cannot be replayed.

use Illuminate\Http\Request;

Route::post('/quiet-social/webhook', function (Request $request) {
    $timestamp = (string) $request->header('X-Social-Timestamp');
    $signature = (string) $request->header('X-Social-Signature');

    $expected = hash_hmac('sha256', $timestamp.'.'.$request->getContent(), config('services.quiet_social.webhook_secret'));

    abort_unless(hash_equals($expected, $signature), 401);
    abort_if(abs(time() - (int) $timestamp) > 300, 401);

    // The same delivery can arrive twice: ignore an X-Social-Delivery you have already processed.
    // …

    return response()->noContent();
});

Exclude this route from your application's CSRF protection.

Delivery and retries

  • A delivery succeeds when your endpoint responds with a 2xx status. Respond quickly and process afterwards: the request is abandoned after 10 seconds, and the connection after 5.
  • Redirects are not followed. A 301 or a 302 counts as a failure: register the final URL.
  • A failed delivery is retried, up to six attempts in total, after 1 minute, 5 minutes, 30 minutes, 2 hours and then 6 hours.
  • The same delivery can arrive more than once. X-Social-Delivery is stable from one attempt to the next: use it to ignore a duplicate.

Suspension

After 10 consecutive failed deliveries (each after all its attempts), the endpoint changes to suspended and receives nothing more. A successful delivery resets the counter to zero.

An endpoint whose URL turns out to be forbidden at sending time — a name that now points to a private address, for example — is suspended immediately.

A suspended endpoint cannot be reactivated through the API. Fix the cause, then use Réactiver (Reactivate) in the dashboard, menu Webhooks: the URL is checked again, the failure counter starts again from zero and the secret does not change. A URL that still leads to a forbidden destination prevents reactivation.