Webhooks quickstart

This guide takes you from nothing to a verified webhook notification in the test environment. You need a way to run a small web server and the credentials of an entity manager.

1. Run an endpoint

Start a server that accepts POST requests, verifies the ob-signature header and answers 204. Pick the language you use from the signature examples; with Node.js:

npm install express

Save the Node.js example as server.js, replace lookupApiKey with a function that returns your API key (you get it in step 3) and enqueue with console.log, add app.listen(3000); at the end, and run it:

node server.js

2. Expose it to the internet

Onebox needs a public URL. While developing, use a tunnel such as ngrok:

ngrok http 3000

Copy the HTTPS forwarding URL it prints, for example https://1a2b-203-0-113-7.ngrok-free.app. Your webhook URL is that address followed by your route: https://1a2b-203-0-113-7.ngrok-free.app/webhooks.

3. Create the webhook

Create the webhook through the Management API, in its Webhooks section, with an access token for your entity. Your operator can also create it for you from the Control Panel.

curl -X POST 'https://api.oneboxtds.net/mgmt-api/v1/webhooks' \
  -H 'Authorization: Bearer <access_token>' \
  -H 'Content-Type: application/json' \
  --data '{
    "scope": "ENTITY",
    "notification_url": "https://1a2b-203-0-113-7.ngrok-free.app/webhooks",
    "events": ["ORDER_PURCHASE", "ORDER_REFUND"]
  }'

Field	Description
scope	ENTITY to receive notifications for all the channels of your entity, or CHANNEL (with channel_id) to receive order notifications of a single channel.
notification_url	The URL from step 2. Use the final URL: redirects are not supported.
events	The <EVENT>_<ACTION> pairs to receive. See the event reference.

The response contains the id of the webhook, which you will receive in the ob-hook-id header, and its api_key. Put the key in your server and restart it. The webhook is created active.

4. Trigger a notification

Make a purchase in the test environment on one of your channels. Within a few seconds your server receives a request like this one:

POST /webhooks HTTP/1.1
Content-Type: application/json; charset=utf-8
ob-event: ORDER
ob-action: PURCHASE
ob-hook-id: c244aa20-afa7-4734-8b95-67d37b66ac04
ob-delivery-id: 5b9f3c1a-7e2d-4a16-9c40-1b3a4d57e802
ob-signature: e93c99261ba2de2eb1b698401a3fdb9e84398230d4b64662d3fd9a2e3c6b50e1

{
  "code" : "9N1FTEJKTQH2",
  "url" : "https://api.oneboxtds.net/orders-mgmt-api/v1/orders/9N1FTEJKTQH2"
}

If the signature is valid your server answers 204 and logs the payload. If it answers 401, paste the body, the key and the signature into the signature tester to find out why.

Don't want to wait for a real purchase? The tester also generates a curl command that sends a correctly signed request to your server.

5. Fetch the order

The notification only says that order 9N1FTEJKTQH2 was purchased. Call the url it contains, with your access token, to get the order details:

curl 'https://api.oneboxtds.net/orders-mgmt-api/v1/orders/9N1FTEJKTQH2' \
  -H 'Authorization: Bearer <access_token>'

Before going live

• Create the production webhook with your production URL; it gets a different API key.
• Answer within 10 seconds and process asynchronously. See Delivery and retries.
• Make processing idempotent: the same notification can arrive more than once.
• Reconcile periodically through the API: a notification can be lost.
• Store the API key as a secret, and plan how to rotate it.