DEVELOPER GUIDE

Stable

Webhooks

• Overview
• How It Works
• Delivery Behavior

Overview

Webhooks deliver real-time notifications from the PointServices platform to an endpoint you host. Instead of polling the Orders API for changes, you register an HTTPS endpoint once and receive an HTTP POST each time a subscribed event occurs.

Every webhook request carries the event metadata and payload in its JSON body, and a JWT in the Authorization header. The JWT proves the request came from PointServices, and its body_sha256 claim binds the token to the exact body delivered, so a verified message cannot have been altered in transit.

Receiving webhooks does not require you to authenticate to us — your endpoint verifies the tokens we send. You will still need an access token to call the Orders API, including when confirming an event against the order it refers to.

How It Works

1. Register your endpoint, the topics you want, and the tenant that generates the events. See Registering.
2. Implement an endpoint that accepts a POST, reads the event from the JSON body, and responds 200 OK. See Implementation.
3. Verify the JWT and the body digest on every request before trusting the body. See Verification.

Delivery Behavior

• Delivery is at least once. The same event may arrive more than once, so use the webhookId field to detect and discard duplicates.
• Your endpoint must be a publicly reachable https URL.
• Responses with a status code >= 500 are retried using exponential backoff.

Always verify the JWT before acting on a webhook body. An endpoint that processes unverified requests will accept event data from anyone who discovers its URL.

---

Table of contents

• Registering
• Implementation
• Verification