API Reference
Log In

Webhooks Setup

Steps to follow to register a webhook service:

  • Get the list of applicable events
  • Subscribe to the particular event, with the webhook URL and event name.
  • Start receiving the webhook payloads on the occurrence of events.
  • Verify the authenticity of the payload.
  • Can Unsubscribe from the event if needed.
  • All the events subscribed are unsubscribed when the merchant unsubscribes the App.
  • API is authenticated as per the existing flow.

Events: ##

Currently available events:

Event -> Corresponding scope

store.Products -> store-inventory:read
store.Orders -> store-orders:read
store.Store -> store-settings:read

👍

NOTE:

You can only subscribe to a particular event if you have an access token with the corresponding scope.

For example, you can subscribe to the event 'store.Products' only if you have the access token with the scope 'store-inventory:read'.

Webhook Payload:##

You will receive the webhook payloads on the occurrence of events.

The payload will be a JSON that follows the existing structure of MDP APIs: MDP Commerce APIs · Instamojo.

👍

Events and their corresponding Payloads

store.Products -> List Products API
store.Orders -> List Orders API
store.Store -> Store Profile details

In addition, the following headers are added for payload verification:

Svix-Id: msg_25oerVGxY1Mg79glr6jU0jAn99J
Svix-Timestamp: 1646198065
Svix-Signature: v1,Mt1YnAFM8holfGEhEuVSD5YGbGLnEKvskJ8KUhYd0xY= //unique signature for each webhook

Webhook verification: ##

Each webhook call includes three headers with additional information that are used for verification:

Svix-Id: the unique message identifier for the webhook message. This identifier is unique across all messages, but will be the same when the same webhook is being resent (e.g. due to a previous failure).

Svix-Timestamp: timestamp in seconds since epoch.

Svix-Signature: the Base64 encoded list of signatures (space-delimited).

Constructing the signed content: ##

The content to sign is composed by concatenating the id, timestamp, and payload, separated by the full-stop character (.). In code, it will look something like this:

signed_content = "${svix_id}.${svix_timestamp}.${body}"

Where body is the raw body of the request. The signature is sensitive to any changes, so even a small change in the body will cause the signature to be completely different. This means that you should not change the body in any way before verifying.

Determining the expected signature: ##

The service uses an HMAC with SHA-256 to sign its webhooks.

So to calculate the expected signature, you should HMAC the signedcontent from above using the base64 portion of your signing secret (this is the part after the whsec prefix) as the key. For example, given the secret whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw you will want to use MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw.

This generated signature should match one of the ones sent in the Svix-Signature header.

The Svix-Signature header is composed of a list of space-delimited signatures and their corresponding version identifiers. The signature list is most commonly of length one. Though there could be any number of signatures. For example:

v1,g0hM9SsE+OTPJTGt/tmIKtSyZlE3uFJELVlNIOLJ1OE= v1,bm9ldHUjKzFob2VudXRob2VodWUzMjRvdWVvdW9ldQo= v2,MzJsNDk4MzI0K2VvdSMjMTEjQEBAQDEyMzMzMzEyMwo=

Make sure to remove the version prefix and delimiter (e.g. v1,) before verifying the signature.

Please note that to compare the signatures it's recommended to use a constant-time string comparison method in order to prevent timing attacks.

Verify timestamp:##

As mentioned above, the service also sends the timestamp of the attempt in the Svix-Timestamp header. You should compare this timestamp against your system timestamp and make sure it's within your tolerance in order to prevent timestamp attacks.