Webhooks

Receive real-time updates when bookings and orders change state.

Delivereasy sends webhooks to notify your system when resources change state. You can configure one webhook URL for staging and one for production. Ask your Delivereasy representative to configure these on your account.

Lastmile webhooks

Delivereasy sends a booking updated webhook each time a booking moves to another stage in the booking lifecycle.

The webhook payload is the same JSON returned from the Retrieve a booking endpoint in the Lastmile API reference. We configure the webhook payload to match the version of API that you are using. By default we set up your webhook with the latest API version, but you can ask us to change that. When you want to upgrade, let us know.

Marketplace webhooks

Delivereasy sends an order created webhook when a new order is placed for your store. The payload includes the full order details.

See the Marketplace API reference for the webhook schema.

Verifying signatures

Validate webhooks to confirm they were sent by Delivereasy. Our webhooks include a signature header containing an HMAC signature of the request body. Your API key is used as the HMAC key.

Lastmile

The signature is in the X-Signature header, calculated as the Base64-encoded HMAC-SHA256 of the raw request body.

# Calculating the expected signature
hmac = OpenSSL::HMAC.digest("sha256", api_key, request_body)
signature = Base64.strict_encode64(hmac)
# Verifying the signature
received_signature = headers["X-Signature"]
expected_hmac = OpenSSL::HMAC.digest("sha256", api_key, request_body)
expected_signature = Base64.strict_encode64(expected_hmac)

unless ActiveSupport::SecurityUtils.secure_compare(received_signature, expected_signature)
  raise InvalidSignatureError
end
Marketplace

The signature is in the X-Delivereasy-Signature header, calculated as the hex-encoded HMAC-SHA256 of the raw request body.

# Calculating the expected signature
signature = OpenSSL::HMAC.hexdigest("sha256", secret_key, request_body)
# Verifying the signature
received_signature = headers["X-Delivereasy-Signature"]
expected_signature = OpenSSL::HMAC.hexdigest("sha256", secret_key, request_body)

unless ActiveSupport::SecurityUtils.secure_compare(received_signature, expected_signature)
  raise InvalidSignatureError
end

Best practices

  • Respond quickly. Return a 200 status code as soon as you receive the webhook. Process the payload asynchronously if your handling logic takes time.
  • Handle duplicates. Webhooks may be delivered more than once. Use the event or booking ID to deduplicate.
  • Verify signatures. Always validate the HMAC signature before trusting the payload.