- Documentation
- API · Version 1.0
- Webhooks
Webhooks
On this page
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, withRetry-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
2xxstatus. Respond quickly and process afterwards: the request is abandoned after 10 seconds, and the connection after 5. - Redirects are not followed. A
301or a302counts 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-Deliveryis 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.