Webhooks allow you to subscribe to server-side notifications of events, such as changes to order state.

Subscribing to Webhooks

You can register webhook endpoints through the settings page of the Photon app. A webhook can be sent for all event types or only those configured. Webhooks can also be authenticated with a shared secret for added security.

Verifying Photon is the Sender

Photon signs all webhook events it sends to your endpoints with a signature in each event's X-Photon-Signature header. You can use this signature to verify the events are sent by Photon. Learn more at Webhook Signature Verification

Webhook Request Headers

All webhook requests have the following headers:

X-Photon-SignaturestringSee Webhook Signature Verification
X-Photon-TimestampstringWhen the request was sent in Unix epoch time seconds.

Webhook Request Body

All webhook requests have a JSON body with the following parameters:

idstringUnique ID for each webhook event
typestringWebhook event, e.g. photon:order:completed
dataobjectData attributes vary based on event type, see Order Events and Prescription Events for more details
timestringISO datetime when the even occurred
subjectstringThe ID of the object that the event relates to

Event Handling

Handling webhook events correctly is crucial to making sure your integration’s business logic works as expected.

Handle Duplicate Events

Webhook endpoints might occasionally receive the same event more than once. We advise you to guard against duplicated event receipts by making your event processing idempotent. One way of doing this is logging the events you’ve processed, and then not processing already-logged events.

Order of events

Photon does not guarantee delivery of events in the order in which they are generated. For example, creating an order might generate the following events:


Your endpoint shouldn’t expect delivery of these events in this order and should handle this accordingly. You can also use the API to fetch any missing objects (for example, you can fetch the order and prescriptions objects using the information from photon:order:sent if you happen to receive this event first).

What’s Next

Details about the data sent for specific events can be found in the below sections