Skip to main content

Webhooks

Webhooks allow Kloutit to notify your system in real-time when important events occur, such as the creation of a new case. When an event is triggered (e.g., Kloutit receives a chargeback notification from a PSP), a CASE_CREATED webhook event is generated and sent to the HTTPS endpoint you have configured.

The events currently sent are:

  • CASE_CREATED - The case has been created based on a dispute from the payment processor, and it is necessary to complete the required information to continue.
  • CASE_DEFENSE_GENERATED - The defense for the case has been created and can be sent to the payment processor.
  • CASE_WON - The payment processor has confirmed that the dispute has been won.

To process webhooks, you need to:

  1. Expose an endpoint on your server.
  2. Set up webhooks in the Kloutit dashboard.
  3. Accept and process webhook events correctly.

Step 1: Expose an Endpoint on Your Server

Webhooks are HTTP callbacks sent to an endpoint on your server. Kloutit requires HTTPS endpoints with TLS 1.2 or TLS 1.3 for security.

To receive webhook events, your server must:

  • Have an accessible endpoint that can receive JSON-encoded HTTP POST requests.
  • Handle incoming webhook requests asynchronously to avoid timeouts.
  • If necessary, allowlist Kloutit's network in your firewall to ensure successful delivery

Step 2: Set Up Webhooks in the Kloutit Dashboard

To configure a webhook:

  1. Navigate to My Organization > Developers in the Kloutit dashboard.
  2. In the Webhook section, enter your endpoint URL.
Once set up, Kloutit will start sending webhook events to your endpoint when relevant actions occur.

Step 3: Accept and Process Webhooks

To ensure reliable webhook processing:

  1. Acknowledge receipt of the webhook event by responding with a 2xx HTTP status code (e.g., 202 Accepted).
    • If Kloutit does not receive a successful response within 10 seconds, the event will be added to a retry queue.
  2. (Recommended) Validate the event to add an extra layer of security. By verifying the event with the verifyEvent call, you'll confirm that the webhook was sent by Kloutit and was not modified during transmission.
  3. Process the event using the available SDKs or Rest API.
  4. Apply your business logic, but only after acknowledging the event to avoid blocking future updates due to processing errors.
    • If an error occurs, respond with an appropriate 4xx or 5xx HTTP error status code.
Retries of failed notifications

If your server fails to respond successfully (e.g., due to downtime or network issues), Kloutit will automatically retry sending the webhook event.

  • First retry: 1 hour after the initial attempt.
  • Subsequent retries: Every 24 hours, up to a maximum of 2 retries.

If all retry attempts fail, the event will no longer be delivered, and manual intervention may be required. Ensure your endpoint is always available to receive updates.

Event Payload

Each webhook event is sent as a JSON-encoded HTTP POST request with the following example:

{
  "eventType": "CASE_CREATED",
  "expedientNumber": "expedientNumber",
  "details": {
    "sector": "DIGITAL_PRODUCT",
    "transactionId": "123456789",
    "transactionDate": "2025-02-12T11:03:43.126Z",
    "bankName": "Sample bank",
    "cardBrand": "Sample card brand",
    "last4Digits": "1234",
    "is3DSPurchase": true,
    "disputeAmount": {
      "currency": "EUR",
      "value": 100
    },
    "purchaseDate": "2025-02-12T11:03:43.126Z",
    "purchaseAmount": {
      "currency": "EUR",
      "value": 100
    },
    "isChargeRefundable": true,
    "customerName": "John Doe",
    "customerEmail": "john.doe@example.com",
    "customerPhone": "612345678"
  }
}