This guide will help you get started with configuring and consuming MidwayPlus Webhooks.

You can manage your webhooks in the Settings > Integrations > API/Webhooks^sandbox section of your MidwayPlus account. Here you should set a name for the webhook, the URL, and a secret.

On this page, you can see the webhooks you have configured, as well as the recent events, and their statuses.

You can resend events, send test events, view the HTTP request and response, and update the settings of webhooks from this page.

Currently, MidwayPlus offers events only for the creation of orders, the order_created event.

MidwayPlus webhooks are in the JSON format. The root of the object contains the event type, a timestamp indicating the transmission time, and a container for the data. Property names, in general, are camelCase. For example

{
    "timestamp": "",
    "eventType": "order_created",
    "data": {
        ....
    }
}

It is strongly recommended that you verify the webhook actually came from MidwayPlus and not a third party. MidwayPlus uses an HMAC of the HTTP request body using the SHA-256 hash function to provide a signature you can use for verification.

MidwayPlus enables a 0-downtime key rotation feature - allowing you to have multiple secrets active at the same time. Each secret generates a hash and all are included in the HTTP headers of the webhook, separated by commas. The webhook can be considered valid as long as at least one signature can be verified with the shared secret. An example signature is shown below with two signatures.

x-Signature: sha256=129a596bfe40b33f56fc4951d4017600513bf07a7d1f990ac2d87155d04c2db1,sha256=2e7d4811311b4e8364dc966c41810dd23827d631e7ab9f932f4b5bf8eca2ff70

The webhook payload also includes a timestamp that represents the transmission time. This timestamp can be validated to prevent replay attacks. Consider validating that the timestamp is within 5 minutes of the actual time you processed the webhook. The timestamp is an ISO 8601 formatted date/time, e.g. 2023‐07‐24T19:13:32Z.

When processing the signature, you should take care to account for multiple signatures, and check for the signature type, i.e. sha256 to be resistant to errors in the event you have multiple secrets defined or MidwayPlus introduces a new signature type.