- Documentation
- PHP SDK · Version 0.1
- Webhooks
Webhooks
On this page
The API notifies your application when a publication changes state, with a signed POST request. The SDK declares endpoints and verifies the notifications received with Webhook::verify(), in constant time and within a tolerance window.
Declare an endpoint
An endpoint is declared in the panel (Webhooks page) or with the SDK, with the webhooks:manage right:
$endpoint = $client->webhooks()->create(
'https://example.com/quiet-social/webhook',
['publication.published', 'publication.failed', 'publication_target.failed'],
);
$endpoint->secret; // whsec_…: returned by this answer only, store it now
$client->webhooks()->test($endpoint->id); // ['delivery_id' => 'whd_…', 'status' => 'pending']
The secret is never returned again: losing it means deleting the endpoint and declaring a new one. webhooks()->list() returns the endpoints of the key, webhooks()->update() changes the address or the events, webhooks()->delete() deletes an endpoint. The third argument of create() limits the endpoint to one brand.
The event catalog, retries and the suspension of an endpoint are described in Webhooks of the API reference.
Verify a notification
use QuietSocial\Sdk\Exceptions\InvalidSignature;
use QuietSocial\Sdk\Webhooks\Webhook;
try {
$event = Webhook::verify(
(string) file_get_contents('php://input'),
getallheaders(),
(string) getenv('QUIET_SOCIAL_WEBHOOK_SECRET'),
);
} catch (InvalidSignature) {
http_response_code(400);
exit;
}
$publication = $event->publication();
if ($publication !== null) {
// A publication.* event: act on the status the body carries.
if ($publication->status === 'published') {
// …
}
} elseif (isset($event->data['target'])) {
// A publication_target.* event: one network, and the id of its publication.
$status = $event->data['target']['status'];
$publicationId = $event->data['publication_id'];
}
http_response_code(204);
verify()checks the HMAC-SHA256 signature ofX-Social-Timestampand the raw body, in constant time, and refuses a timestamp more than 300 seconds away from now. The fourth argument changes the window; the fifth sets the current time, for tests.- Pass the body exactly as received: decoded then encoded again, it would no longer match.
- The secret is required. An empty or blank secret throws
InvalidArgumentException: a missing environment variable fails loudly instead of accepting forged notifications. - Header names can be in any case, and values strings or lists, as
getallheaders()and$request->headers->all()give them. - An untrusted request (a missing header, a timestamp outside the window, a wrong signature, a body that is not a JSON object) throws
InvalidSignature: answer with an error status and never act on its body.
What is signed, and what is not
Only the timestamp and the body are signed. $event->name (X-Social-Event) and $event->deliveryId (X-Social-Delivery) come from headers that whoever can replay a request could change. Deduce the event from the body:
| Body | Event | Reading |
|---|---|---|
{"publication": …} |
publication.* |
$event->publication() returns the publication, with its targets. |
{"target": …, "publication_id": …} |
publication_target.* |
$event->data['target'] and $event->data['publication_id']. |
{"destination": …} |
destination.disabled |
$event->data['destination']. |
{"social_connection": …, "destinations": …} |
social_connection.requires_reconnect |
$event->data['social_connection']. |
{"message": …, "sent_at": …} |
webhook.test |
Nothing to do but answer 2xx. |
Decide on the body (the publication and its status) and use the name as a hint. $event->deliveryId is stable across attempts, which helps skip a delivery already processed, but keep the processing itself idempotent: applying the status the body carries twice must change nothing. $event->signedAt is when this attempt was signed, not when the event happened: a retried delivery is signed again.
In Laravel
use Illuminate\Http\Request;
use QuietSocial\Sdk\Exceptions\InvalidSignature;
use QuietSocial\Sdk\Webhooks\Webhook;
Route::post('/quiet-social/webhook', function (Request $request) use ($webhookSecret) {
try {
$event = Webhook::verify(
$request->getContent(),
$request->headers->all(),
$webhookSecret,
);
} catch (InvalidSignature) {
abort(400);
}
// …
return response()->noContent();
});
$webhookSecret is the whsec_… secret, read from your own setting (an environment variable behind a configuration value, for instance). Exclude this route from the CSRF protection of your application, and answer quickly: process the notification in a job if it takes work.