Configure Webhooks via API

Ordergroove can send webhook events to an endpoint or endpoints of your choosing. In order to set up which webhook events you want triggered to which endpoint, you’ll need to:

1. Configure each target endpoint that you want events to be sent to
2. Configure which events you want sent to the target endpoint

Authentication

We recommend you set up webhooks directly in the Ordergroove merchant dashboard, under Developers > Webhooks. If you need to set webhooks up via API, please contact your Customer Success Manager or technical resource at Ordergroove to discuss authentication options.

Creating a Target Endpoint

Destination

• Staging: https://staging.webhooks.ordergroove.com/webhook_targets/
• Production: https://webhooks.ordergroove.com/webhook_targets/

1
{
2
  "merchant": "abc12345",
3
  "target_url": "https://www.mywebhooktargeturl.com/receive/",
4
  "enabled": true
5
}

For more information on all targets that exist, how to update targets, or how to get target metrics, check out our Webhook Targets REST endpoint documentation for additional details.

Defining Events to Send to a Webhook Target

Once you’ve created a Webhook Target, you can define which events you want to be sent to that endpoint. The ID returned in the response of the Target Creation step is what will be used in this API request for the target_id in the path parameter.

Destination

• Staging: https://staging.webhooks.ordergroove.com/webhook_targets/{target_id}/filters
• Production: https://webhooks.ordergroove.com/webhook_targets/{target_id}/filters

To define multiple events, use a pipe separator as shown:

1
{"pattern": "subscription.*|order.*"}

Subscriber Event Filters

• subscriber.create
• subscriber.cancel
• subscriber.* (for all events)

Subscription Event Filters

• subscription.create (this event is not triggered when creation is from your Ordergroove Admin)
• subscription.cancel
• subscription.sku_swap
• subscription.reactivate
• subscription.change_frequency
• subscription.change_components
• subscription.change_quantity
• subscription.change_shipping_address
• subscription.change_payment
• subscription.change_live
• subscription.* (for all events)

Order Event Filters

• order.change_shipping_address
• order.change_payment
• order.change_billing
• order.change_next_order_date (this event is not triggered when creation is from your Ordergroove Admin)
• order.skip_order
• order.send_now
• order.cancel
• order.success
• order.generic_error
• order.reject
• order.reminder
• order.retryable_placement_failure
• order.* (for all events)

Order Item Event Filters

• item.create
• item.change_quantity
• item.remove
• item.item_subscribe
• item.update_price
• item.successfully_placed
• item.* (for all events)

Receiving Event Notifications

Payload Verification

Requests will be signed using the HMAC-SHA256 algorithm with a symmetric key we store and share with you at the time of configuration.

A webhook event will be delivered with the request header OrderGroove-Signature which will contain:

• a timestamp of transmission
• a hex-encoded representation of a signature generated with HMAC-SHA256

OrderGroove-Signature: ts=1592570791,sig=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd

It is strongly encouraged to verify the authenticity of events. A Python example below shows how one might go about using the JSON values provided in the header to verify the signature.

1
ts = "1592570791"
2
payload = u''
3
sig_key = "shared symmetric key"
4
sig_input = "{ts}.{payload}".format(ts=ts, payload=payload)
5
6
hash_obj = hmac.new(key=bytes(sig_key, 'ascii'), msg=bytes(sig_input, 'utf-8'), digestmod=hashlib.sha256)
7
generated_sig = hash_obj.hexdigest() # "5257a869e7...."
8
return generated_signature == header_signature

As shown above, via the sig_input variable, the signature is driven by:

• the timestamp provided in the request header
• a period (.)
• the payload of the webhook event

Signing Key Retrieval

Signing keys are considered sensitive data and should only be retrieved when absolutely necessary.

• Staging: https://staging.webhooks.ordergroove.com/webhook_targets/<target_id>/signing_key
• Production: https://webhooks.ordergroove.com/webhook_targets/<target_id>/signing_key

1
{
2
  "signing_key": "5f15ef298dc15df9bc6eda35"
3
}

Signing Key Rotation

Like passwords, keys should be rotated on a regular basis. While we do not dictate this cadence (yet), you may rotate keys for a particular target on demand. Once this process is activated, events will be delivered with one signature for each active key.

Patch Request Destination:

• Staging: https://staging.webhooks.ordergroove.com/webhook_targets/<target_id>/signing_key/rotate
• Production: https://webhooks.ordergroove.com/webhook_targets/<target_id>/signing_key

1
{
2
  "signing_key": "5f15ef298dc15df9bc6eda35",
3
  "expiring_signing_key": "GBBYToAvYGBBYToAvYGBBYToAvY",
4
  "signing_key_expiry": 1597260663
5
}

The signing_key_expiry field will tell you when the expiring_signing_key will be discarded and no longer used. Consecutive requests to this endpoint will generate a new value in the signing_key, but the timer for the signing_key_expiry will not update. You will have 24 hours from the first time this endpoint is hit to make sure your applications are using the new key, whichever it may be. Any subsequent requests sent to the “Signing Key Retrieval” endpoint will only respond with the new key.

Key Rotation

If the rotation of a signing key occurred, there will be two sig fields present, providing one signature for each key.

sig=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd,sig=da32affa62cdca35257a869e7e56ff536d0ce8e108d8bdcebefa51cad7e77a0e

Retries and Automatic URL Disabling

• Retries: If a target does not return a 2xx HTTP response status, the delivery of the event will be retried for no more than 3 days using an exponential back-off for each subsequent retry attempt. After 3 days, the delivery will be marked as a failure. The first retry will be delayed for 60 seconds and will be subsequently doubled.
• URL Disabling: After 3 days, if a target does not provide a 2xx HTTP response status, the URL will automatically be disabled. Any success will reset the disable logic. Re-enabling a disabled URL will also reset the disable logic.

Subscriber Events Response

1
{
2
  "id": "mmmm4444nnnn3333pppp",
3
  "type": "subscriber.create",
4
  "created": 1622589211,
5
  "data": {
6
    "object": {
7
      "type": "subscriber",
8
      "merchant": "aaaa1111bbbb2222cccc",
9
      "merchant_user_id": "dddjjjjkk3343",
10
      "subscription": "ssss3333llll2222bbbb",
11
      "session_id": "aaaa1111bbbb2222cccc.450125.1299622365",
12
      "first_name": "John",
13
      "last_name": "Smith",
14
      "email": "john.smith@email.com",
15
      "phone_number": "555-555-5555",
16
      "phone_type": 2,
17
      "phone_type_display": "mobile",
18
      "live": true,
19
      "created": 1298407706,
20
      "last_updated": 1301323663,
21
      "extra_data": {},
22
      "locale": 1,
23
      "locale_display": "en-us"
24
    }
25
  }
26
}

Subscription Events Response

1
{
2
  "id": "mmmm4444nnnn3333pppp",
3
  "type": "subscription.create",
4
  "created": 1622589211,
5
  "data": {
6
    "object": {
7
      "type": "subscription",
8
      "merchant": "aaaa1111bbbb2222cccc",
9
      "public_id": "zzzz9999yyyy8888xxxx",
10
      "customer": "m1234576",
11
      "product": "SKUabc",
12
      "components": [
13
        {"product": "product_1"},
14
        {"product": "product_2"}
15
      ],
16
      "extra_data": {},
17
      "quantity": 1,
18
      "price": null,
19
      "frequency_days": 56,
20
      "reminder_days": 10,
21
      "every": 2,
22
      "every_period": 2,
23
      "every_period_display": "Weeks",
24
      "cancelled": 1301325188,
25
      "cancel_reason": "",
26
      "cancel_reason_code": null,
27
      "session_id": "aaaa1111bbbb2222cccc.450125.1299622365",
28
      "merchant_order_id": "12345678",
29
      "live": true,
30
      "external_id": null,
31
      "created": 1300375961,
32
      "start_date": "2021-03-25",
33
      "offer": "a748aa648ac811e8af3bbc764e106cf4",
34
      "payment": "070001bc02fd11e99542bc764e1043b0",
35
      "shipping_address": "66c25cd0564011e9abc5bc764e107990",
36
      "updated": 1300375961
37
    }
38
  }
39
}

Order Events Responses

1
{
2
  "id": "mmmm4444nnnn3333pppp",
3
  "type": "order.success",
4
  "created": 1622589211,
5
  "data": {
6
    "object": {
7
      "type": "order",
8
      "merchant": "aaaa1111bbbb2222cccc",
9
      "public_id": "zzzz9999yyyy8888xxxx",
10
      "customer": "m1234576",
11
      "payment": "a748aa648ac811e8af3bbc764e106cf4",
12
      "shipping_address": "66c25cd0564011e9abc5bc764e107990",
13
      "discount_total": "0.00",
14
      "shipping_total": "0.00",
15
      "sub_total": "0.00",
16
      "tax_total": "0.00",
17
      "total": "0.00",
18
      "extra_data": {},
19
      "generic_error_count": 0,
20
      "order_merchant_id": null,
21
      "place": "2021-04-06",
22
      "rejected_message": null,
23
      "status": 1,
24
      "status_display": "Unsent",
25
      "tries": 0,
26
      "cancelled": null,
27
      "created": 1301093861
28
    }
29
  }
30
}

Item Events Responses

1
{
2
  "id": "mmmm4444nnnn3333pppp",
3
  "type": "item.create",
4
  "created": 1622589211,
5
  "data": {
6
    "object": {
7
      "type": "item",
8
      "merchant": "aaaa1111bbbb2222cccc",
9
      "public_id": "zzzz9999yyyy8888xxxx",
10
      "customer": "m1234576",
11
      "product": "SKUabc",
12
      "order": "1234e74444dd115555d8bc7cccc043b0",
13
      "subscription": "bc7cccc043b01234e74444155"
14
    }
15
  }
16
}