Easyship can send webhook events to notify your application when a particular event has occurred. This is useful for some endpoints, for example, Confirm And Buy Labels, which do not give you a real-time response. If you subscribe to the webhook to receive shipment status updates, you will be notified when the shipment's label is ready without polling our API.
The payload for each webhook event will include information about the related API response. Your provided endpoint should be set up to receive a HTTP POST request, and must always return a 200 HTTP response.
Configuring your Webhooks Settings
You can register your webhook endpoint (URL) via the Easyship Dashboard. Simply click “Add new webhook”, enter your “Webhook Endpoint URL“. Select the event types you wish to receive notifications for, click “Create” and you're set!
Before you activate your webhook endpoints, you can test your endpoint by clicking the "Test" button next to each event. If the test is successful, you will see the message - "Webhook test succeeded".
We recommend returning a 200 HTTP response immediately or we will consider the webhook POST action to have failed.
{
"label_received": true
}
If this is your first time setting up a webhook, we suggest testing your endpoint with ngrok. It's amazingly simple and useful. You can even take a closer look at the event payload as you test each event.
After you activate your webhook endpoints, you will start to get incoming events. You can make deactivate or delete the endpoint at any time.
Verifying an Incoming Event with Easyship's Signature
To prevent your application from a replay attack, we recommend that you verify all incoming webhook events by checking for our unique signature, X-EASYSHIP-SIGNATURE, in the headers.
The signature is a JSON web token that can be decoded with the value of your secret_key. You can find it on the dashboard's webhook configuration page. It will always be a hash string starting with webh_.
secret_key = 'webh_092dflkjhwelkjr109834wlkejhr8sdh'
signature = request.env['X-EASYSHIP-SIGNATURE']
JWT.decode signature, secret_key, true, { algorithm: 'HS256' }
#=> [{easyship_company_id: 'easyship_company_id'}, {...algorithm information...}]
Webhook Suspension
If a webhook's publish process continuously fails for a specific endpoint up to 30 times, we will automatically suspend your subscription of that endpoint.
You can check and re-activate it from the dashboard.