Setting up webhooks

A webhook sends a message to one of your own systems the moment something happens in your store, such as an order being placed. You add webhooks under Settings, then Webhooks: pick an event and give the address on your system, and Orbit posts to it each time the event happens. This guide is for the person who runs the store. The developer who builds the receiving end should also read the Webhooks guide on the developer portal.

Considerations

• You need the Update store settings permission. Store Owners have it. Without it the Webhooks card does not appear.
• The address must start with https:// and be reachable from the internet. Orbit rejects private and internal addresses.
• You can add one webhook per event from this page.
• Each webhook has its own signing secret. Orbit shows it once, when you add the webhook. Pausing keeps the secret. Deleting destroys it.
• The message names the record that changed, such as an order id, not the whole record. Your system reads the details through the API with an API key. See Creating and managing API keys.
• Adding, pausing, resuming and deleting a webhook is recorded in the Activity Log.

Open the Webhooks page

1. From your Orbit dashboard, go to Settings.
2. Under Team & Access, click Webhooks. On a new store the page reads No webhooks yet.

Each webhook is one row: the event name, the address it posts to, and an Inactive badge when it is paused. Three buttons sit at the right: Pause deliveries (or Resume deliveries), Delivery history and Delete.

Pick an event

Events are named like order.created. The list covers:

• Orders: created, updated, confirmed or cancelled.
• Fulfilment: created or updated.
• Payments: succeeded, failed, awaiting manual review, refunded in full or in part, or cancelled.
• Payouts: completed or failed.
• Products, customers and carts: a product or customer created, updated or deleted; a cart updated.
• Plugins: installed, activated, deactivated or uninstalled.
• B2B: companies, company users, company locations, B2B catalogues, payment terms and B2B invoices. These only fire on stores using B2B, which is included in the Enterprise plan.

The full list, with what each message carries, is in the topic catalogue on the developer portal.

Add a webhook

1. On the Webhooks page, click Add webhook.
2. Under Event, open the list and pick the event.
3. Under Endpoint URL, type the address your developer gave you, such as https://erp.example.com/hooks/orbit.
4. Click Add webhook. If something is wrong, the dialog says what, for example The endpoint must use HTTPS. A private address is refused.
5. The Copy your signing secret now dialog opens.

Save the signing secret

Your developer uses this secret to check that each message really came from your store. Orbit shows it only now.

1. Click the copy icon next to the secret. Give it to your developer, or paste it into your password manager. Do not send it by email or chat.
2. Read Verify every delivery. The link How to verify the signature opens the developer portal. Verifying webhook signatures has the same steps with code samples.
3. Click I have saved the secret. The secret is gone from the screen and the webhook is on the list.

Warning: If the secret is lost, there is no way to see it again. Delete the webhook, add it again, and give the new secret to your developer.

What Orbit sends

• One message per event, as an HTTPS POST with a JSON body.
• Your system must answer with a success status within 10 seconds. It should answer first and do its work after.
• If it does not answer, or answers with an error, Orbit tries again, up to 4 attempts in total, starting 5 seconds later and waiting longer each time.

Pause and resume a webhook

Pause a webhook when your system is down or being worked on. The address and the secret are kept.

1. On the webhook's row, click Pause deliveries. The message Webhook endpoint paused appears and the row shows Inactive.
2. To start again, click Resume deliveries. The message Webhook endpoint resumed appears.

Note: Events that happen while a webhook is paused are not sent later. Messages already waiting to go out are dropped too.

Check delivery history

1. On the webhook's row, click Delivery history. The Deliveries dialog lists the 20 most recent deliveries, newest first. Before the first event it reads No deliveries yet. They appear here after the first matching event.
2. Each row shows a status, the HTTP status your system returned or no response, and the time. success means accepted, pending means Orbit is still retrying, failed means every attempt failed.
3. Click Close.

Repeated failed rows with no response usually mean the address is wrong or your system is down.

Delete a webhook

1. On the webhook's row, click Delete.
2. The Delete webhook? dialog says events for that topic will stop being delivered immediately. Click Delete.
3. The message Webhook subscription deleted appears. The secret is destroyed with it.

Webhooks your developer adds through the API also appear here. You can pause or delete them, and revoking the API key removes them.

Related guides

• Verifying webhook signatures
• Creating and managing API keys
• Getting started with the Orbit API
• Automating your store with Workflows