Skip to navigation
Data & IntegrationsWebhooks & APIsWebhooks

Webhook Authentication

Verify webhook request authenticity using signing keys and understand the key rotation process
View as Markdown

Rotating signing key of a webhook route

Verification keys are used to sign webhook requests, allowing the recipient to verify that the requests are genuinely issued by Ordergroove. In the event the verification key of a given route needs to be changed — because it got compromised or is due for routine security updates — it is possible to start a key rotation process so that webhook requests start being signed with a new key.

Key Rotation Process

When the key rotation process is initiated for a webhook route, a transitional period of 24 hours begins. During this period, the Ordergroove-Signature header in webhook requests will include signatures for both the new and the old verification keys.

The format for these headers will be:

ts=<TIMESTAMP>,sig=<PAYLOAD_SIGNED_WITH_NEW_KEY>,sig=<PAYLOAD_SIGNED_WITH_OLD_KEY>

This dual-signature approach ensures a smooth transition, allowing the recipient to verify the webhook requests using either the old or the new key.

Transition Completion

After the 24-hour transition period, the Ordergroove-Signature header will revert to its standard format, containing only the new key signature:

ts=<TIMESTAMP>,sig=<PAYLOAD_SIGNED_WITH_NEW_KEY>

At this point, the old verification key becomes obsolete for request verification. It is imperative that all webhook recipients update their systems to use the new verification key within this 24-hour window to maintain uninterrupted verification of webhook requests.

To initiate a verification key rotation process for a given webhook, follow these steps:

  1. Log in to Ordergroove.
  2. Go to Developers > Webhooks.
  3. Locate the webhook you want to rotate, click the 3 dots, and select Regenerate key.
The Webhooks page in RC3 with three webhooks listed. The three-dot menu on the second row, Test webhook route, is open and outlined in orange, showing Details, Edit, Disable, Regenerate key, and Delete, with Regenerate key highlighted.
  1. Confirm the operation by clicking Regenerate key.
The Regenerate Verification Key confirmation dialog in RC3, over the dimmed Webhooks page. A red warning headed Unexpected bad things can happen if you regenerate it says the current Verification Key will only be valid for the next 24 hours, and that regenerating can break your integration if you do not understand the logic first. An outlined Regenerate key button sits at the bottom right.
  1. After the operation completes successfully, the new key is available for copying from the Verification Key column and adopting in the recipient servers.
The Webhooks page in RC3 with three webhooks listed. The Verification key column, its header and all three rows, is outlined in orange, and each row shows a masked key with a copy icon beside it.