Osigu Payments provides webhook functionality to keep providers updated on key events related to invoice registration and cash advance requests. Webhooks allow providers to receive real-time notifications for specific events, enabling seamless data synchronization between Osigu Payments and the provider’s internal systems. Below is an overview of the available webhooks, their triggers, and the data structure sent with each notification.

Available Webhooks

New Cashout Request Created

Triggered each time the provider on the Osigu Payments platform creates a new cashout request.

This webhook notifies the provider of a newly initiated cash advance request, allowing their systems to record the request details and begin monitoring its progress immediately.

• Payload Example:
  JSON

  {
    "event": "cashout_request.created",
    "cashout_request_id": "a1b2c3d4-e5f6-7890-1234-56789abcdef0",
    "currency_code": "USD",
    "requested_amount": 1500.00,
    "requested_invoice_count": 3,
    "request_date": "2023-06-10T10:15:30Z",
    "status": "REQUESTED"
  }
  

  
  

Cashout Request Status Update

Triggered whenever the status of a cashout request changes, such as moving from REQUESTED to APPROVED or from PENDING_PAYMENT to PAID.

This webhook enables providers to track the status progression of each cashout request in real-time. It is beneficial for monitoring when payments are approved, rejected, or completed.

• Status Updates Include:
  • APPROVED
  • UNDER_REVIEW
  • REJECTED
  • PENDING_PAYMENT
  • PAID
  • CANCELLED
  • PAYMENT_PROCESSOR_ERROR
• Payload Example:
  JSON

  {
    "event": "cashout_request.status_update",
    "cashout_request_id": "a1b2c3d4-e5f6-7890-1234-56789abcdef0",
    "status": "PAID",
    "paid_amount": 1500.00,
    "payment_date": "2023-11-12T14:22:00Z",
    "payment_reference": "pay-7890-xyz123"
  }
  

Invoice Status Update in Cashout Request

It is triggered whenever an individual invoice within a cashout request experiences a status update as a result of its inclusion in the cashout request.

This webhook ensures that the provider's system can accurately reflect the status of each invoice within a cash advance request, particularly when invoices become eligible or ineligible for payment.

• Payload Example:
  JSON

  {
    "event": "invoice.status_update",
    "account_receivable_invoice_id": "b2d4f6a8-5678-4321-8765-abcdef123456",
    "invoice_number": "INV-1001",
    "status": "PENDING",
    "risk_level": "LOW",
    "eligible_advance_percentage": 80,
    "eligible_advance_amount": 1200.00
  }
  

Webhook Delivery and Security

Each webhook event is delivered as an HTTP POST request to a specified endpoint configured by the provider. Osigu Payments requires all webhook requests to include a signature, which the provider must validate upon receipt to ensure security and data integrity. This signature guarantees that the webhook event originated from Osigu Payments and was not tampered with during transmission.

Signature Mechanism

1. Generating the Signature

Each webhook request includes a signature in the HTTP header named X-Osigu-Signature. This signature is generated using HMAC-SHA256 encryption, combining the webhook payload (body) with a shared secret key provided to each provider.

The signature is computed as follows:

signature = HMAC-SHA256(secret_key, payload)

The secret_key is a unique key shared securely with each provider during their webhook setup process.

2. Validating the Signature

Upon receiving a webhook event, the provider’s system must:

1. Retrieve the X-Osigu-Signature header from the request.
2. Recompute the HMAC-SHA256 hash of the received payload using the same secret_key.
3. Compare the recomputed hash with the X-Osigu-Signature value in the header. If the values match, the request is authenticated as coming from Osigu Payments. If not, it should be rejected.

• Example Validation in Python:

  Python

  import hmac
  import hashlib
  
  # Provided shared secret key
  secret_key = b'your_shared_secret_key'
  
  # Retrieve the payload and signature from the request
  payload = request.get_data()  # Body of the webhook request
  received_signature = request.headers.get('X-Osigu-Signature')
  
  # Recompute the signature using the secret key
  computed_signature = hmac.new(secret_key, payload, hashlib.sha256).hexdigest()
  
  # Validate the received signature against the computed signature
  if hmac.compare_digest(computed_signature, received_signature):
      print("Signature is valid, process the request")
  else:
      print("Signature verification failed, reject the request")
  

Retry Mechanism

Osigu Payments will automatically retry delivery with an exponential backoff schedule if a webhook delivery attempt fails. This ensures the reliable delivery of critical notifications.

Endpoint Configuration

Providers must configure their webhook endpoints with a secure URL using HTTPS, version 1.2 or higher, to ensure encrypted data transmission. Through the Osigu Payments dashboard, providers can specify their preferred webhook URL and the types of events for notifications and manage security settings.

By validating the signature, providers ensure that only verified and authorized webhook requests from Osigu Payments are processed, safeguarding their data and systems.