Webhooks

You can listen for events from MovingWaldo on your endpoint to track the progress of your leads on our platform.

How to enable webhooks

First, you must already have a co-branded platform (https://<PLATFORM>.booking.movingwaldo.com).

Then, you can contact us to enable webhooks and provide us with :

• Production endpoint url
• Staging endpoint url (optional)

In return, we will send you a secret key for each endpoints.

How to link events with your customers

Whenever you send a lead to your MovingWaldo platform, you can add a query parameter eid. This eid will be included in each webhook events to allow you to track the progress of your leads.

Here, you can find documentation of all query parameters.

Webhooks request

• Events are sent with POST requests.
• Payloads are delivered as JSON-formatted strings using UTF-8 encoding.
• Requests time out after 15 seconds, and HTTP redirects are not followed.
• User agent include the webhook version (current version is 1.0.0)
  MovingWaldo-API-1.0.0
• Transport Security: HTTPS (TLS v1.2 or higher) required.
• All payloads are signed using HMAC (SHA256) and should be validated on your end with the provided secret key.
• Requests are not retried upon failure.

info

Your webhooks are locked to your API version. We'll deliver security patches and non-breaking updates, but we will never automatically migrate you to a new major release.

Verifying Request Integrity

To ensure the security and integrity of the data sent to your endpoint, you must verify that the webhook originated from our servers and has not been tampered with. We sign each payload using an HMAC (Hash-based Message Authentication Code) with the SHA-256 algorithm.

Key Specifications

• Algorithm: HMAC-SHA256
• Secret Key: A 32-byte hexadecimal string.
• Header: X-Hub-Signature-256
• Payload: The raw, unparsed request body.

warning

Critical Security Note: Timing Attacks Always use a constant-time comparison function to prevent timing-based side-channel attacks. (ex: crypto.timingSafeEqual with Node.js, hmac.compare_digest with Python or constant_time_eq::constant_time_eq with Rust).

Webhooks payload

Webhooks events

Event	Description
LEAD_CREATED	When your customer fill the form.
QUOTE_ACCEPTED_BY_CUSTOMER	When your customer accept a quote and pay a deposit.
MOVE_COMPLETED	When the date of the move is reached.
CUSTOMER_RATED_MOVING_COMPANY	When your customer rate his movers.

Common fields for each events

Field	Type	Optional	Description
event	string		Event (see Webhooks events)
timestamp	number		Unix timestamp (in milliseconds) of the event
moveId	string		MovingWaldo unique ID
movingCompany	string		Name of the selected moving company (if applicable)
eid	string		Your internal id (if provided)

Fields for CUSTOMER_RATED_MOVING_COMPANY

Field	Type	Optional	Description
rating	number		Rating between 1 and 5 stars

Payload example

POST https://example.movingwaldo.com/demo HTTP/1.1
Content-Type: application/json
User-Agent: MovingWaldo-API-1.0.0
X-Hub-Signature-256: 4f9a2b7d8e1c63a5f0b2d4e689c1a3b572e4f608d9a7b2c5e1f3a0d8c6b4e9f2

{
  "timestamp": 1776681029433,
  "moveId": "5d9ab759-9adb-490c-896a-9dccf148a0fc",
  "eid": "YOUR-OWN-ID",
  "event": "CUSTOMER_RATED_MOVING_COMPANY",
  "movingCompany": "The Foobar company inc.",
  "rating": 4,
}