Webhooks

Introduction

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:

Header	Type	Description
X-Photon-Signature	string	See Webhook Signature Verification
X-Photon-Timestamp	string	When the request was sent in Unix epoch time seconds.

Webhook Request Body

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

Param	Type	Description
id	string	Unique ID for each webhook event
type	string	Webhook event, e.g. `photon:order:completed`
data	object	Data attributes vary based on event type, see Order Events and Prescription Events for more details
time	string	ISO datetime when the even occurred
subject	string	The 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:

photon:order:created
photon:order:sent
photon:order:processing

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).