Webhook

Our recommended best practice for securing webhooks involves either HMAC validation, which has first-class support in each of our client libraries, or using basic authentication and HTTPS on your endpoint. This will help prevent any altering of any information communicated to you by EasyPost, prevent any third parties from seeing your webhooks in transit, and will prevent any third parties from masquerading as EasyPost and sending fraudulent data. EasyPost performs certificate validation and requires any TLS-enabled (HTTPS) webhook recipients to have a certificate signed by a public trusted certification authority. We do not support sending webhooks over SSLv2, SSLv3, or any connection using so-called export-grade ciphers. For documentation on how to set up your server with TLS, we recommend Mozilla's guide to Server-Side TLS and Qualys's SSL/TLS deployment best practices guide.

Securing a webhook via HMAC validation is simple. Pass a webhook_secret with your request to create or update a Webhook as shown example below. Once a webhook secret is setup, we will return its signature via the X-Hmac-Signature header on every Event sent to your webhook URL. All that is left is to validate that the signature we sent you matches the webhook secret you initially sent us. You can accomplish this by calling the validate_webhook() function if using one of our client libraries (the naming convention of this function may differ per language), and passing in your webhook secret, headers, and the webhook payload. If the signatures match, the function will return the webhook data, otherwise it will throw an error to protect your system from the incoming webhook.

Basic authorization requires that a username and password combination be included alongside the webhook URL during Webhook creation.

An example may look like this: https://username:secret@www.example.com/easypost-webhook. When an Event triggers in our system, we'll deliver a webhook to this endpoint along with anAuthorization header that you will need to validate the credentials for. If the credentials do not match what we have stored in our system for this webhook (the Authorization header sent to this endpoint), the webhook should be rejected.

{
  "id": "hook_9dd6e2fcba4c11ee92767be0e8b3db48",
  "object": "Webhook",
  "mode": "test",
  "url": "http://example.com",
  "created_at": "2024-01-24T00:07:52Z",
  "disabled_at": null
}

1curl -X POST https://api.easypost.com/v2/webhooks \
2  -u "EASYPOST_API_KEY": \
3  -H 'Content-Type: application/json' \
4  -d '{
5    "webhook": {
6      "url": "example.com"
7    }
8  }'

1{
2  "id": "hook_9dd6e2fcba4c11ee92767be0e8b3db48",
3  "object": "Webhook",
4  "mode": "test",
5  "url": "http://example.com",
6  "created_at": "2024-01-24T00:07:52Z",
7  "disabled_at": null
8}

1curl -X GET https://api.easypost.com/v2/webhooks \
2  -u "EASYPOST_API_KEY":

1{
2  "webhooks": [
3    {
4      "id": "hook_9f1fa072ba4c11ee9b29733b326f964d",
5      "object": "Webhook",
6      "mode": "test",
7      "url": "http://example.com",
8      "created_at": "2024-01-24T00:07:54Z",
9      "disabled_at": null
10    }
11  ]
12}

1curl -X GET https://api.easypost.com/v2/webhooks/hook_... \
2  -u "EASYPOST_API_KEY":

1{
2  "id": "hook_9e64905cba4c11eeaac53dd08b571ecc",
3  "object": "Webhook",
4  "mode": "test",
5  "url": "http://example.com",
6  "created_at": "2024-01-24T00:07:53Z",
7  "disabled_at": null
8}

1curl -X PATCH https://api.easypost.com/v2/webhooks/hook_... \
2  -u "EASYPOST_API_KEY":

1{
2  "id": "hook_9ff05f5aba4c11ee882b0fe795304884",
3  "object": "Webhook",
4  "mode": "test",
5  "url": "http://example.com",
6  "created_at": "2024-01-24T00:07:56Z",
7  "disabled_at": null
8}

1curl -X DELETE https://api.easypost.com/v2/webhooks/hook_... \
2  -u "EASYPOST_API_KEY":

1{}