Guide
Webhooks
Pholio sends a signed HTTPS POST to your endpoint when something happens to one of
your deliveries, so your system can react straight away instead of polling.
On this page:
- Events and payloads
- How webhooks are delivered: headers, responses, retries and ordering
- Verifying signatures
- Setting up a webhook and troubleshooting
Events
Choose which events each webhook receives when you add or edit it in Pholio.
| Event | Sent when |
|---|---|
delivery_created | A delivery is created for your company. |
delivery_updated |
One or more of these fields of a delivery change: status, requested date, due date, assigned photographer, booking status, priority, style, approval, correction or custom reference. Changes to other fields don't send this event. |
editing_complete |
A retouch order for the delivery is completed and the edited photos are uploaded. It is sent again each time the order is completed, for example after a rejected order has been fixed. |
webhook_test | You choose Test webhook in Pholio. Always sent, whichever events the webhook is subscribed to. |
Payloads
The body is a small JSON object with the event name and the delivery ID in entityId.
It doesn't say what changed. Fetch the delivery with
GET /api/v1/deliveries/{delivery}
to get its current state.
{"event":"delivery_updated","entityId":123}
editing_complete also includes the ID of the completed retouch order:
{"event":"editing_complete","entityId":123,"retouchOrderId":456}
After editing_complete, fetch the delivery to get the new edited_urls of its photos.
The URLs change each time a photo is edited, so don't reuse stored ones. If the delivery uses automatic
delivery, the photos have already been delivered to the customer when the webhook is sent.
A test webhook has no delivery:
{"event":"webhook_test","entityId":null}
The API reference describes every payload as a schema.
How webhooks are delivered
The request
Each webhook is an HTTP POST to your URL with these headers:
Content-Type: application/json
Accept: application/json
X-Pholio-Webhook-Timestamp: 1760000000
X-Pholio-Webhook-Signature: sha256=4ffb2183cf000f17af42bc97c0910e8eb794729d2de6793f5a218a0d04d2d77d
X-Pholio-Webhook-Timestamp is when the attempt was sent, as a Unix timestamp in seconds.
X-Pholio-Webhook-Signature lets you check that the request came from Pholio. See
Verifying signatures.
Responding
- Return any
2xxstatus as soon as you have accepted the webhook. The response body is ignored. - Respond within 15 seconds, and accept the connection within 5. Do slow work, such as fetching the delivery, in your own background queue.
- Any other status counts as a failed attempt.
Retries
Pholio makes up to 3 attempts. It retries after connection errors, timeouts and
408, 429 or 5xx responses. Other 4xx responses, such
as 400 or 401, are not retried. Retries follow the failed attempt within seconds,
so they won't bridge a longer outage of your endpoint.
Redirects
Register the final URL of your endpoint. If it answers with a 301, 302 or
303 redirect, the request is repeated as a GET without a body, so the webhook
is lost.
Ordering and duplicates
- Webhooks are sent from a queue and can arrive out of order. For example, a
delivery_updatedfor a status change and theediting_completethat caused it can arrive in either order. - The same webhook can arrive more than once, for example when your endpoint processed a request but timed out before answering.
- Because the payload only carries the delivery ID, the safest approach is to fetch the delivery each time and work from its current state.
Verifying signatures
Every webhook is signed with the webhook's signing secret, which Pholio shows once when you create the webhook. To verify a request:
- Read the raw request body. Don't parse and re-encode the JSON first, as that changes the bytes that were signed.
- Build the signed message: the timestamp header, a full stop, then the raw body:
{timestamp}.{body}. - Calculate the HMAC-SHA256 of that message with your signing secret, as lowercase hex, and add the prefix
sha256=. - Compare the result with
X-Pholio-Webhook-Signatureusing a constant-time comparison. - Reject requests whose timestamp is more than about 5 minutes from your clock, to limit replay attacks.
PHP
$secret = getenv('PHOLIO_WEBHOOK_SECRET');
$timestamp = $_SERVER['HTTP_X_PHOLIO_WEBHOOK_TIMESTAMP'] ?? '';
$signature = $_SERVER['HTTP_X_PHOLIO_WEBHOOK_SIGNATURE'] ?? '';
$body = file_get_contents('php://input');
$expected = 'sha256=' . hash_hmac('sha256', $timestamp . '.' . $body, $secret);
if (!hash_equals($expected, $signature) || abs(time() - (int) $timestamp) > 300) {
http_response_code(401);
exit;
}
$payload = json_decode($body, true);
// Queue your own processing of $payload['event'] and $payload['entityId'] here.
http_response_code(204);
Node.js (Express)
const crypto = require('crypto');
const express = require('express');
const app = express();
// Keep the raw body: the signature covers the exact bytes Pholio sent.
app.post('/pholio/webhook', express.raw({ type: 'application/json' }), (req, res) => {
const timestamp = req.get('X-Pholio-Webhook-Timestamp') || '';
const signature = req.get('X-Pholio-Webhook-Signature') || '';
const expected = 'sha256=' + crypto
.createHmac('sha256', process.env.PHOLIO_WEBHOOK_SECRET)
.update(timestamp + '.' + req.body.toString('utf8'))
.digest('hex');
const valid = signature.length === expected.length
&& crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))
&& Math.abs(Date.now() / 1000 - Number(timestamp)) <= 300;
if (!valid) return res.sendStatus(401);
const payload = JSON.parse(req.body.toString('utf8'));
// Queue your own processing of payload.event and payload.entityId here.
res.sendStatus(204);
});
Test your code
With these values, your code should produce the signature below. Skip the timestamp age check for this test.
| Signing secret | example-signing-secret |
|---|---|
| Timestamp | 1760000000 |
| Raw body | {"event":"delivery_updated","entityId":123} |
| Signature | sha256=4ffb2183cf000f17af42bc97c0910e8eb794729d2de6793f5a218a0d04d2d77d |
Rotating the secret
If a signing secret may have been exposed, choose Roter signeringsnøkkel (rotate signing secret) in the webhook's action menu. The old secret stops working immediately, so update your endpoint with the new secret straight away. Requests that fail verification in the meantime are retried only if you answer with a retryable status.
Setting up a webhook
- As a company administrator, open your company page in Pholio and select the API tab.
- Select Legg til webhook (Add webhook), enter your HTTPS URL and choose the events.
- Store the signing secret that is shown. It is shown only once.
- Choose Test webhook in the webhook's action menu and check that your endpoint verifies and accepts it.
You can change the URL and events later with Rediger (Edit). Deaktiver (Deactivate) stops all deliveries to the webhook and keeps its history. Only HTTPS URLs are accepted. See Getting started for the full walkthrough, including the API key you need to fetch deliveries.
Testing and troubleshooting
Use Test webhook in Pholio to send a real, signed request to your endpoint. The Test Request button on the webhooks in the API reference sends an unsigned sample from your browser, so it fails signature verification.
Webhook-historikk (webhook history) on the API tab lists every attempt with the time, event, URL, the status code your endpoint returned (or the connection error) and the number of attempts. Venter means the webhook is still queued.
| What you see | What to check |
|---|---|
| No webhooks arrive | That the webhook is active and subscribed to the event, and that API and webhooks are still enabled for your company. Send a test webhook to check the connection. |
| A connection error or timeout in the history | That the URL is reachable from the internet over HTTPS with a valid certificate, and that you answer within 15 seconds. |
401 from your own endpoint |
That you verify the raw body (not re-encoded JSON), use the current signing secret, and that your server clock is correct. Check your code with the test values. |
Your endpoint receives a GET without a body |
Your URL redirects. Register the final URL. |
404 when you fetch a delivery right after delivery_created |
The webhook can arrive just before the delivery is fully saved. Retry the request after a few seconds. |
404 when you fetch a delivery in other cases |
That your API key has the delivery:read scope and belongs to the same company. See Authentication. |
