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

Choose which events each webhook receives when you add or edit it in Pholio.

EventSent when
delivery_createdA 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_testYou 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 2xx status 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_updated for a status change and the editing_complete that 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:

  1. Read the raw request body. Don't parse and re-encode the JSON first, as that changes the bytes that were signed.
  2. Build the signed message: the timestamp header, a full stop, then the raw body: {timestamp}.{body}.
  3. Calculate the HMAC-SHA256 of that message with your signing secret, as lowercase hex, and add the prefix sha256=.
  4. Compare the result with X-Pholio-Webhook-Signature using a constant-time comparison.
  5. 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 secretexample-signing-secret
Timestamp1760000000
Raw body{"event":"delivery_updated","entityId":123}
Signaturesha256=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

  1. As a company administrator, open your company page in Pholio and select the API tab.
  2. Select Legg til webhook (Add webhook), enter your HTTPS URL and choose the events.
  3. Store the signing secret that is shown. It is shown only once.
  4. 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 seeWhat 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.