How the signature is generated
The webhook signature is generated using the HMAC (Hash-based Message Authentication Code) method with the SHA-256 algorithm. This method combines the sign-secret with the transmitted data (payload) to create a unique signature. Any modification to the webhook content or headers will change the signature, making any tampering attempt evident.Code example (Python) for consuming the Webhook
The example below shows how to create an interface to receive real-time vehicle data via Webhook using Python and the Flask library. This application must be hosted online at a URL that mobway can access to send the information./webhook route is where the server expects to receive webhooks sent by mobway. This route is configured to accept only POST HTTP requests. The webhook function associated with this route is asynchronous, allowing the server to handle multiple requests simultaneously and efficiently, without blocking execution while previous requests are being processed. Inside the webhook function, the payload (the webhook data) and the digital signature are extracted from the request. The signature is sent in the request header under the name X-Signature. The function then delegates signature verification and data processing to the handle_request function.
The mobway server that sends data through the webhook expects an HTTP 200 response code, indicating that the data was received successfully. If any other error code is returned, the server will retry sending the data successively until a predefined limit is reached. To ensure that no data is lost, the information is stored so it can be retrieved through other means if necessary. If the issue with receiving data persists, webhook delivery will be interrupted, and mobway will contact you to review and resolve the situation.
The handle_request function is responsible for validating the authenticity of the signature and processing the received data. It receives the payload and the signature as parameters. First, it calls the verify_signature function to compare the received signature with the expected signature. Validation is performed using HMAC with the SHA-256 algorithm, combining the payload with the sign-secret stored on the server. If the signature is not valid, the function aborts the operation and returns an HTTP 403 status code, indicating that the request was rejected because it could not be authenticated. If the signature is valid, the data is converted from a JSON string into a dictionary and processed in a separate thread.
The verify_signature function plays a key role in webhook security. It generates the signature locally using HMAC with SHA-256 and the sign-secret, and then compares that signature with the signature received in the request.
Payload example
The payload below is sent to the client as soon as vehicle data is received and processed by mobway. The structure includes all available data that the client is authorized to access, organized by VIN:Response