Webhooks allow partners to be notified when important events happen in XCover.
When one of those events are triggered, we will send an HTTP POST payload to the webhook's configured URL. Webhooks can be used to send a customer notification, initiate a policy renewal process or perform any custom logic.
To establish webhooks, partners can provide to their CSE:
1. Listener URL
2. Authentication Key & Secret
3. Support URL
4. Requested events (CSE may propose or suggest these as part of solutioning).
We will provide an HTTP signature generated on our end in Authorization header and the api key itself in X-Api-Key header. We will base the signature on your provided key pair. You can use the same HMAC based algorithm for signature verification, if required. Please use the information from the signature header to check which hash algorithm is used in order to validate the request. Currently, webhook requests are signed using sha256 algorithm.
In case of multiple failures with the webhook notification, where the partner supplied endpoint does not respond with a 200 OK, we will try the webhook for up to 3 times.
Authentication
Your webhook API endpoint should implement HMAC authentication to verify that the API request was sent and signed by XCover.
import base64
import hashlib
import hmac
from urllib.parse import unquote
# You will provide your assigned Client Solution Engineer with an API key and secret
# they will configure the XCover platform
api_key = "--your-api-key--"
secret = "--your-secret--"
# This is just an example, you would obtain this from your server library
# E.g. a Flask server
# from flask import Flask, request
# app = Flask(__name__)
# @app.post('/my-xcover-webhook')
# def xcover_webhook():
#. request_headers = request.headers
# return do_everything_below()
request_headers = {
'X-Api-Key': '--api-key--',
'Authorization': '--signature--',
'Date': 'Thu, 27 Feb 2025 05:01:47 GMT'
}
# Extract signature from the request headers
auth_header = request_headers.get('Authorization', '')
if not auth_header.startswith('Signature '):
raise ValueError("Invalid Authorization header")
auth_parts = dict(
part.split('=', 1) for part in
auth_header.replace('Signature ', '').split(',')
)
received_signature = unquote(auth_parts.get('signature', '').strip('"'))
# Compute the expected signature
date_header = request_headers.get('Date')
if not date_header:
raise ValueError("Missing Date header")
raw = f"date: {date_header}"
expected_hash = hmac.new(
secret.encode("utf-8"),
raw.encode("utf-8"),
hashlib.sha256
).digest()
expected_signature = base64.b64encode(expected_hash).decode('utf-8')
is_valid = hmac.compare_digest(expected_signature, received_signature)
BOOKING_CREATED
Description: The payload is sent in a webhook to the Partner whenever the Booking is Created through an API Request.
