# Webhook Event Object Shapes

**Last Updated:** April 2025

This document describes the JSON structure of event payloads sent via custom webhooks.

## 1. Event Shape

All webhook events delivered by our system follow a standard pattern. This provides a consistent top-level structure.

**Structure:**


```json
{
  "event_id": "string",
  "event_type": "string",
  "data": "object"
}
```

- event_id (string):
  - A unique identifier for this specific event instance.
Example: "evt_01H7XZR6Q7X7Q7X7Q7X7Q7X7Q7"
- event_type (string):
  - A string identifying the type of event that occurred (e.g., payment.succeeded, payment.failed).
The value of event_type determines the structure of the data object.
Example: "payment.succeeded"
- data (object):
  - An object containing the specific details for the event indicated by event_type.
See below for an example structure for payment-related events (PaymentEvent).


## Event types

Below is a list of event types we support

- payment.success
- payment.created
- payment.failure
- event.test


## Payment Events


```json
{
  "event_id": "string",
  "event_type": "string",
  "data": {
    "payment_id": "string",
    "merchant_id": "string",
    "environment_id": "string",
    "amount": "int32",
    "currency": "string",
    "status": "string",
    "metadata": {
      "your_key": "your_value"
    }
  }
}
```

- payment_id (string):
  - The unique identifier for the payment.
  - Example: "pay_01H7XZS0P5Y5Y5Y5Y5Y5Y5Y5Y5"
- merchant_id (string):
  - The unique identifier for the merchant associated with this payment.
  - Example: "mer_01H7XT4F3G8G8G8G8G8G8G8G8G"
- environment_id (string):
  - The unique identifier for the environment (e.g., live, test) in which this payment occurred.
  - Example: "env_01H7XTA9K2R2R2R2R2R2R2R2R2"
- amount (int32):
  - The payment amount, typically in the smallest currency unit (e.g., cents for USD).
  - Example: 10000
- currency (string):
  - The three-letter ISO currency code.
  - Example: "USD"
- status (string):
  - The current status of the payment (e.g., SUCCEEDED, FAILED).
  - Example: "SUCCEEDED"
- metadata (object):
  - All metadata included when the payment was created
  - Example: {"external_customer_id": "my_customer_id"}