Nowadays, there is almost no application that works independently. There are third-party services like payment gateways, CRM systems, and logistics providers, which have to be integrated. Webhooks are an excellent option to achieve data sharing between applications in real time: the source actively sends messages to the Odoo instance instead of the inefficient polling approach.
Nevertheless, in case when a webhook fails to identify the sender of received requests, it will be under threat from three different sides: access without permission, forged requests, and harmful data. Below, there will be described how to cope with these threats.
What Is a Webhook?
Webhook stands for “HTTP Callback,” which is an HTTP POST triggered by some action; it is an easy-to-use event-notification system that operates via HTTP POST.
- The payment provider issues a notification whenever the payment is finished.
- The eCommerce application notifies Odoo about the creation of a new order.
- Order shipment status changed by the shipping application.
That means that Odoo does not poll an external API every few minutes but is ready to receive a webhook request and process the received information instantly.
Why Do You Need Webhook Authentication?
Since webhook endpoints can be reached via the Internet, anyone who knows the endpoint’s URL could send a request to it.
With no authentication, your app could:
- Accept fraudulent webhook requests
- Process wrong or harmful data
- Make unauthentic entries
- Start unwanted business procedures
Webhook authentication makes sure that each incoming request is made by an authenticated sender before being processed by Odoo.
Common Webhook Authentication Methods
Various services have various means of authentication. The popular forms of authentication are as follows:
Secret Token:
A predefined token is included in the request headers. Odoo compares the received token with the stored secret before processing the request.
Example Header
Authorization: Bearer your_secret_token
This is one of the most simple and popular forms of authentication.
Signature Verification
Several systems use the shared secret to create a cryptographic signature for the request payload.
Odoo creates a signature of its own using the secret key and matches it with the request signature.
In case of equality of the two signatures, the request can be regarded as genuine.
Such an approach is more secure since it ensures that the payload is unaltered as well.
API Key Authentication
Some Webhook Providers add an API key to the request header.
Example:
X-API-Key: your_api_key
Odoo checks the key prior to processing the webhook.
Basic Authentication:
There are some services that use HTTP Basic Authentication using a username and password.
While it may be supported by numerous systems, it is still less popular than token or signature authentication.
Implementing Webhook Authentication in Odoo 19
We should implement a webhook endpoint that would be checking the authentication token before handling the request.
Step 1: Create a Controller
A controller should be created within your custom module.
from odoo import http
from odoo.http import request
import json
class WebhookController(http.Controller):
@http.route( '/webhook/payment', type='http', auth='public', methods=['POST'], csrf=False )
def payment_webhook(self, **kwargs):
token = request.httprequest.headers.get("Authorization")
expected_token = "Bearer my_secure_token"
if token != expected_token: return request.make_response( json.dumps({"error": "Unauthorized"}), headers=[('Content-Type', 'application/json')], status=401 )
payload = request.httprequest.get_data(as_text=True)
# Process webhook payload here
return request.make_response( json.dumps({"status": "Success"}), headers=[('Content-Type', 'application/json')] )
In this case, the token is taken from the request header, and then it is checked against the correct token. If the token is not valid, then the 401 Unauthorized error code is returned.
Step 2: Store the Secret Securely
Do not use hardcoded authentication tokens in your Python code.
It is recommended that you store the secret in Odoo System Parameters or in your module’s parameters.
This way, you will be able to change the secret without editing the code.
Example:
expected_token = request.env['ir.config_parameter'].sudo().get_param( 'my_module.webhook_secret' )
Step 3: Verify the Incoming Payload
Once authentication is successful, validate the payload prior to handling it.
Examples of this include:
- Make sure all required fields are present.
- Validate data types.
- Deal with null values or invalid entries.
- Discard malformed JSON.
Validation will avoid unexpected errors in your application.
Step 4: Log Webhook Requests
Webhook request logs make debugging easier.
Data you can log includes:
- Timestamp
- Type of event
- Status code
- Authentication status
- Error messages
DO NOT LOG any sensitive data like authentication details or customer information.
Best Practices for Webhook Authentication
The following guidelines are useful for creating robust webhook integrations within Odoo 19:
- Use HTTPS always.
- Keep your authentication secrets safe.
- Do not hard-code any token inside your source code.
- Check signatures when possible.
- Validate each received payload.
- Use correct HTTP response codes.
- Log all requests for debugging.
- Rotate your authentication secrets regularly.
- Limit access to your webhooks whenever possible.
Common Mistakes to Avoid
A lot of developers inadvertently put security vulnerabilities into place when they implement webhooks.
Some common pitfalls are:
- Accepting unauthenticated requests
- Embedding secrets in the code
- Omitting signature checks
- Logging secret information
- Processing malformed or partial requests
- Returning success responses even if authentication fails
By avoiding these pitfalls, you can have better integrations.
Webhook authentication plays an important role in integrating any service into Odoo 19. If you integrate payment gateways, shipping services, and third-party business apps, then it will be helpful to verify that your incoming requests are legitimate and prevent unwanted and insecure access to your system.
You can create reliable and secure webhook endpoints using token validation, secret handling, payload verification, and security practices.
To read more about A Complete Overview of Webhooks in Odoo 19, refer to our blog A Complete Overview of Webhooks in Odoo 19.