Setting up a Webhook

Create, configure, disable, re-enable, and delete webhook routes in RC3

Creating a webhook

This is the first step to start using Ordergroove’s webhooks system. Multiple webhooks can be created if necessary.

Follow these steps for each webhook you intend to create:

Log in to Ordergroove.
Go to Developers > Webhooks.
If you haven’t created any webhooks yet, click on the Create webhook button at the bottom of the page.

The Webhooks page in RC3 before any webhook exists, with an illustration, the message No webhooks, a link to the developer documentation, and a dark Create webhook button below them.

If there are already some webhooks created, click on the Create button at the top of the page.

The Webhooks page in RC3 with one webhook already listed, and the dark Create button at the top right, next to a Documentation link. The table's columns are Name, URL, Verification key, and Status. The one row, Disabled webhook route, has a masked verification key and a Disabled status.

Configure the webhook to be created.
1. Choose a name for the webhook.
2. Choose a webhook target.
3. Select the event types the webhook is going to subscribe to.
4. Optional: Click on Advanced settings to customize the outgoing payloads for the current webhook.

The New Webhook page in RC3. The General section has the Webhook name field set to Test webhook route and the URL field, the destination for this target, filled in. The Events section lists Subscriber events, Subscription events, Order events, and Item events, with Subscriber events expanded and its three events checked: subscriber.create, subscriber.cancel, and subscriber.subscriptions_created. The Advanced settings button below the list is outlined in orange, and the Cancel and Save buttons sit at the bottom.

Click Save at the bottom of the page.
After the webhook saves, it’ll redirect you back to the Webhooks page with the new webhook listed.

The Webhooks page in RC3 after saving, with two webhooks in the table: the earlier Disabled webhook route, with a Disabled status, and the new Test webhook route, with an Enabled status. Each row shows a masked verification key with a copy icon beside it, and a three-dot menu.

Upon successful creation of the new webhook route, the Ordergroove system will immediately activate it. From this point forward, whenever any of the subscribed event types occur within the Ordergroove system, a webhook will be automatically delivered to the configured target. Additionally, if you chose to customize the outgoing payloads when creating the webhook (optional step 5), this configuration is going to be reflected in the outgoing requests. Otherwise, default payloads are going to be sent.
Make sure you double check that the webhook is working correctly. To verify the requests coming from the webhook that you created, copy the verification key of the webhook and use it on the receiving servers to verify the requests’ authenticity.

Subscribing to event types for a webhook route

The webhooks system lets you subscribe to specific event types for each route so that only webhooks tied to the selected types are sent. The different event types available in Ordergroove are represented as strings in the format <ENTITY>.<EVENT>. For instance:

order.reminder — Triggered when an order reminder is sent.
subscription.created — Occurs when a new subscription is created.
item.change_quantity — Indicates a change in the quantity of an item.

By limiting the event types a route is subscribed to, you can significantly reduce unnecessary traffic to the targets. This focused approach ensures that receiving systems only process the events that are most pertinent to your operations, enhancing efficiency and clarity.

The steps to subscribe to specific event types for an existing webhook route are as follows:

Log in to Ordergroove.
Go to Developers > Webhooks.
Locate the webhook you want to edit, click the 3 dots, and click Edit.

The Webhooks page in RC3 with three webhooks listed. The three-dot menu on the last row, Test webhook route 2, is open and outlined in orange, showing Details, Edit, Disable, Regenerate key, and Delete, with Edit highlighted.

Go to the Events section and select the desired event types. You can select all events of a given group.

The Events section of the webhook edit page in RC3, with a checkbox beside each event group and each event. Subscriber events is expanded, with subscriber.create, subscriber.cancel, and subscriber.subscriptions_created checked. Subscription events is expanded, with only subscription.cancel, subscription.change_components, and subscription.change_payment checked among its ten events. Order events is expanded, with order.change_shipping_address checked and order.change_payment unchecked, and the image ends partway down that list.

Click Save at the bottom of the page.
After you save, events of your selected types in Ordergroove are going to start being communicated to the webhook target.

Disabling a webhook

If you want to stop receiving webhooks from Ordergroove for a given route, it is possible to disable it so that no new webhook events are transmitted to the specified target. Note that if there is a different webhook with the same configured target which is still enabled, webhooks are still going to arrive at that target through this other route.

The steps to disable a webhook route are as follows:

Log in to Ordergroove.
Go to Developers > Webhooks.
Locate the webhook you want to disable, click the 3 dots, and select Disable.

Confirm you want to disable the selected webhook.

The confirmation dialog for disabling the webhook named Test webhook route 2, over the dimmed Webhooks page in RC3. A red warning headed Unexpected bad things can happen if you disable it says that while you can enable a webhook, disabling it means no events are going to reach this target and those events are going to be lost. An outlined Disable button sits at the bottom right.

Once it’s disabled, no new Ordergroove webhooks are going to be delivered to this route.

Re-enabling a webhook

A webhook can be easily re-enabled. The only caveat is that all the events that happened during the time the webhook was disabled are not recoverable — only events happening after re-enabling the route are going to be sent through it.

Log in to Ordergroove.
Go to Developers > Webhooks.
Locate the webhook you want to enable, click the 3 dots, and select Enable.

The Webhooks page in RC3 with three webhooks listed. The three-dot menu on the second row, Test webhook route 2, which has a Disabled status, is open and outlined in orange, showing Details, Edit, Enable, Regenerate key, and Delete, with Enable highlighted.

Once it’s complete, Ordergroove webhook events are going to resume their deliveries to the specified target using the route’s current configuration.

Deleting a webhook

If you are certain that a given route is not going to be used anymore, it is possible to delete it so that it doesn’t get listed on the Webhooks page. This action cannot be undone.

Log in to Ordergroove.
Go to Developers > Webhooks.
Locate the webhook you want to delete, click the 3 dots, and select Delete.
Confirm the action by clicking I understand.

The first delete confirmation dialog in RC3, for the webhook named Test webhook route 2, over the dimmed Webhooks page. A red warning headed Unexpected bad things can happen if you delete it says that while you can recreate a webhook, deleting it means losing the current webhook subscription and its associated events. An outlined I understand button sits at the bottom right.

Confirm the action by typing the word DELETE.

The second delete confirmation dialog in RC3, for the webhook named Test webhook route, over the dimmed Webhooks page. Under the prompt Please enter DELETE to proceed, the text field has DELETE typed in it, and a red Delete button with a warning triangle sits at the bottom right.

When the webhook is successfully deleted, no webhook events are going to be sent through this route anymore. The only way to undo this operation is to manually create a new route with the same configuration as the route that was just deleted.