Webhook Events Overview

What is a Webhook Event?

A webhook event is a real-time notification sent from the Capa API to a partner's specified URL whenever a specific action or change occurs within our system. These events could relate to a variety of operations, such as user verification (KYC) updates, transaction status changes, and more.

General Structure of Webhook Events

Each webhook event sent by the Capa API follows a standardized structure to ensure consistency and ease of integration. Below is the general structure of a webhook event:

• Event Type: A category defining the nature of the event.
  • We currently support this type of events:
    • KYC
    • TRANSACTION
• Event Name: A specific identifier of the event type (e.g., VERIFIED_USER, COMPLETED_ON_RAMP).
• Payload: Contains relevant data and details specific to the event type.

Example of a General Webhook Event

Here’s a generic example of how a webhook event might look:

{
  "type": "TRANSACTION",                // Event Type: Can be 'KYC', 'TRANSACTION', etc.
  "event": "COMPLETED_ON_RAMP",         // Event Name: Specific to the event (e.g., 'VERIFIED_USER', 'RECEIVED_USER_CRYPTO')
  // The rest values are event specific
}

Security and Authentication

To ensure secure communication, each webhook event is signed using HMAC (Hash-based Message Authentication Code) authentication. This signature is computed using a secret key shared between Capa and the partner. The partner must validate the signature to confirm that the notification is genuine and has not been tampered with.

Common Event Types

1. KYC (Know Your Customer) Events:

   • Triggered when there are updates or changes in the user's identity verification process.
   • Examples: VERIFIED_USER, REJECTED_KYC, REVIEW_NEEDED_KYC.

2. Transaction Events:

   • Triggered when there are updates or changes related to user transactions, such as cryptocurrency exchanges, purchases, or cancellations.
   • Examples: COMPLETED_ON_RAMP, COMPLETED_OFF_RAMP, RECEIVED_USER_CRYPTO, CANCELLED_ON_RAMP.

Handling Webhook Events

1. Registering a Webhook URL

Partners need to register a single webhook URL where they want to receive notifications. This URL should be provided via the designated endpoint:

• Endpoint: PUT [api/partner/v1/webhook-settings](https://docs.capa.fi/reference/partnerwebhooksettingscontroller_update)
• Request Body Example:
  JSON

  {
    "url": "https://your-webhook-endpoint.url"
  }
  

2. Receiving Webhook Notifications

When an event occurs, the Capa API sends a POST request to the partner's registered webhook URL. Partners should ensure their endpoints are always available to receive these notifications.

3. Validating the Signature

Partners should validate the HMAC signature included in the event header to ensure the integrity and authenticity of the notification. This helps protect against tampered or spoofed events.

4. Responding to Webhook Events

Partners must respond with a 200 OK status to acknowledge receipt of the webhook. If the Capa API does not receive this acknowledgment, it will retry the delivery of the event up to 5 times with exponential backoff.

Error Handling and Retries

• Automatic Retries: If the Capa API does not receive a 200 OK response from the partner's endpoint, it will automatically retry up to 5 times with increasing delays between attempts.
• Manual Retries: Partners can manually request a retry of failed notifications by making a POST request to a dedicated endpoint.

Best Practices for Handling Events

• Ensure Endpoint Availability: Make sure your webhook URL is always available and responsive to receive notifications.
• Handle Retries Gracefully: Design your system to handle duplicate events gracefully in case of retries.
• Secure Your Webhook Endpoint: Validate the HMAC signature and use HTTPS to ensure secure communication.
• Log and Monitor Events: Log all incoming events and monitor them to detect any issues early.

Summary

The Capa API's webhook event system provides partners with real-time notifications of significant events, allowing them to stay informed and take timely action. By understanding the general structure, security measures, and handling practices, partners can effectively integrate with the webhook system and ensure smooth operation.