Webhooks

Webhooks allow Osigu to notify external systems about specific events as they happen in real-time.

When one of these events occurs, the platform sends an HTTP request to a pre-configured URL provided by the payer. All webhooks must adhere to the predefined contract and specifications set by Osigu, ensuring consistency and compatibility.

Events Supported by Webhooks

The following events are reported through webhooks:

Each event has a specific format and includes a unique event type in the request payload, which can be used to identify the reported event type.

---

Webhook Expectations

All webhooks provided by the payer must meet the following requirements:

• Protocol: Webhook URLs must use the HTTPS protocol.
• Response Codes: To indicate successful processing, webhooks must respond with an HTTP status code in the 2xx range.
• Retry Mechanism: If a response is outside the 200-299 range, the notification will be marked as failed, and the system will enter a retry process. Each retry occurs after an increasing delay until the retry limit is reached.
• Contract Adherence: The attribute names in the request body and response body must strictly match the definitions provided by Osigu.

---

Security Requirements

To ensure the security of webhook interactions, the following measures are mandatory:

1. HTTPS Protocol:

   • All webhook URLs must operate under the HTTPS protocol with a minimum version of 1.2.

2. Signature Validation:

   • Each webhook request includes an X-Osigu-Signature header containing an HMAC-SHA256 signature. The signature is generated using a shared secret key and the webhook payload. The payer must validate this signature to ensure the request's authenticity.

   Example Validation in Python:

   Python

   import hmac
   import hashlib
   
   # Provided shared secret key
   secret_key = b'your_shared_secret_key'
   
   # Retrieve payload and signature from request
   payload = request.get_data()  # Raw body of the request
   received_signature = request.headers.get('X-Osigu-Signature')
   
   # Compute the HMAC-SHA256 signature
   computed_signature = hmac.new(secret_key, payload, hashlib.sha256).hexdigest()
   
   # Validate the signature
   if hmac.compare_digest(computed_signature, received_signature):
       print("Signature is valid.")
   else:
       print("Invalid signature. Reject the request.")