Webhook Signature Verification

When you create a webhook subscription in Parsel, a unique secret key is generated for your account. This secret is base64 encoded and returned to you during the subscription creation process.

This base64-encoded secret string is used to sign all webhook payloads sent to your callback URLs. Each webhook request includes a signature in the x-parsel-signature header, allowing you to verify that the request genuinely came from Parsel and wasn't tampered with.

How to Verify the Signature

To verify the webhook signature:

1. Extract the signature from the x-parsel-signature header
2. Use your base64-encoded secret string directly in your HMAC calculation
3. Generate HMAC-SHA256 using your secret and the request body
4. Compare the generated signature with the received signature

Example: Signature Verification

Your Base64-Encoded Secret

Sgt5mu5MsfB4WiJ+Vlkb0FobRQHTndtTex5NQlm0a4w=

Sample Webhook Payload

{
  "happened_at": "2025-08-11T13:52:57.044999Z",
  "id": "4b56f0e5-8f30-4345-8b2e-5b477a04388b",
  "payload": {
    "shipment_id": "123e4567-e89b-12d3-a456-426614174000",
    "shipping_label_id": "123e4567-e89b-12d3-a456-426614174000",
    "tracking_code": "1234567890",
    "tracking_events": [
      {
        "message": "RECEIVED IN DESTINATION",
        "occurred_at": "2025-08-08T07:57:00Z",
        "source": "OnTrac",
        "status": "IN_TRANSIT",
        "status_detail": "RECEIVED IN DESTINATION",
        "tracking_location": {
          "city": "COMMERCE",
          "country": "US",
          "state": "CA",
          "zip": "90040"
        }
      }
    ]
  },
  "status": "pending",
  "topic": "LABEL_TRACKING_UPDATED",
  "webhook_subscription_id": "4b56f0e5-8f30-4345-8b2e-5b477a04388a"
}

Expected Signature

When Parsel sends this webhook, the x-parsel-signature header will contain: 3378f069d08d32c2e4b3b23792c2e312ced122669983fca4c1cec9c286a7a33d