Webhook Events & Event Types

Core Event Types

Our webhook system currently supports the following core event types:

1. `chargeback.created`

Triggered when: A new chargeback is received and created in the system

This event fires immediately when we receive a new chargeback from any of your connected PSPs (Payment Service Providers). The payload includes all available chargeback data at the time of creation.

Event Payload Structure

All webhook events follow this standard structure:

TypeScript Interface

interface WebhookEvent {
  event: string;                    // Event type identifier
  timestamp: string;                // ISO 8601 timestamp in UTC
  data: ChargebackDto;             // Full chargeback object
  webhookId: string;               // Unique webhook delivery ID (UUID)
  merchantUuid: string             // Unique merchant identifier (UUID)
}

interface ChargebackDto {
  id: string;                                    // Justt chargeback ID (UUID)
  chargebackId: string;                         // PSP chargeback ID
  psp?: string;                                 // PSP name (enum)
  currency?: string;                            // Currency code (e.g., USD, EUR)
  amount?: number;                              // Chargeback amount
  postingDate?: string;                         // ISO 8601 date when chargeback posted
  transactionCreatedDate?: string;              // ISO 8601 date when transaction created
  dueDate?: string;                             // ISO 8601 date when response is due
  pspStatus?: string;                           // PSP status (enum)
  status?: string;                              // Justt system status (enum)
  lifecycleStage?: string;                      // Lifecycle stage (enum)
  transactionId?: string;                       // PSP transaction ID
  arn?: string;                                 // Acquirer Reference Number
  externalTransactionIdentifier?: string;       // External transaction identifier
  merchantReferenceName?: string;               // Merchant identifier in PSP
  reasonCode?: string;                          // Card scheme reason code
  reason?: string;                              // Chargeback reason
  cardScheme?: string;                          // Card scheme (VISA, MC, AMEX, etc.)
  enrichmentRatio?: number;                     // Data enrichment ratio (0-1)
}

Example Webhook Payload

Here's a complete example of a chargeback.created event:

{
  "event": "chargeback.created",
  "timestamp": "2024-06-10T14:30:45.123Z",
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "chargebackId": "CB_2024_001234",
    "psp": "stripe",
    "currency": "USD",
    "amount": 299.99,
    "postingDate": "2024-06-10T09:15:30.000Z",
    "transactionCreatedDate": "2024-05-25T16:42:18.000Z",
    "dueDate": "2024-06-24T23:59:59.000Z",
    "pspStatus": "needs_response",
    "status": "waiting_for_data",
    "lifecycleStage": "chargeback",
    "transactionId": "txn_1PQR2S3T4U5V6W7X",
    "arn": "74537604221234567890123",
    "externalTransactionIdentifier": "ORD-2024-05-25-7891",
    "merchantReferenceName": "merchant_acme_store",
    "reasonCode": "4855",
    "reason": "Goods/Services Not Provided",
    "cardScheme": "VISA",
    "enrichmentRatio": 0.73
  },
  "webhookId": "webhook-delivery-uuid-12345",
  "merchantUuid": "acct_merchant_123456"
}

Event Filtering

When configuring your webhook endpoint, you can:

Subscribe to all events - Receive all event types (default behavior)
Subscribe to specific events - Choose only the events you need to reduce noise

We recommend starting with all events for testing, then filtering to specific event types for production use.