Webhook setup

In this we'll look at how webhooks can be setup. You will learn how to register a webhook, how testing works and how you can receive them. We also explain how you can verify the authenticity of a webhook.

1. Register a webhook

To learn more about registering a new webhook, please view the webhook resource

{
  "webhook": {
    "group": "order",
    "action": "create",
    "ulr": "https://12345.ngrok.io/"
  }
}

2. Test the webhook

For local projects you can use a service like ngrok to expose make your project publicly available

3. Receive the webhook

After you register an endpoint, eWarehousing sends an HTTP POST request to the URL specified every time that event occurs. The HTTP POST request's parameters contain the JSON relevant to the event that triggered the request.

All webhooks require a valid HTTPS address.

4. Verify the webhook

Before you process a webhook, we strongly advise to first verify that the webhook was sent from eWarehousing. You can verify the webhook by calculating a digital signature.

Each webhook request includes a base64-encoded X-Hmac-SHA256 header, which is generated using the webhook's secret key along with the request body.

import hmac
import hashlib
import base64

WEBHOOK_SECRET = 'secret_key_registered_at_webhook'

def verify_webhook(data, hmac_header):
    digest = hmac.new(WEBHOOK_SECRET.encode('utf-8'), data, digestmod=hashlib.sha256).digest()
    computed_hmac = base64.b64encode(digest)

    return hmac.compare_digest(computed_hmac, hmac_header.encode('utf-8'))

def handle_webhook():
    verified = verify_webhook(request.data, request.headers.get('X-Hmac-SHA256'))

    if not verified:
        return abort(401)

    # Process webhook payload
    # ...

    return response(200)

5. Responding to the webhook

Your webhook should respond with a 200 OK response to acknowledge the data is received. Non-2xx responses are marked as failed and will be retried automatically.

It is important to know that eWarehousing does not follow redirects.

Retry strategy

Webhooks have a 10-second timeout period and a set retry period for webhook subscriptions.

eWarehousing waits 10 seconds for a response to each request of a webhook. If there's no response, or an error is returned, then we retry the webhook once per hour, for a maximum of 10 times.

To avoid timeouts and errors, consider deferring app processing until after the webhook response has been successfully sent.