Webhook Events

Complete reference of all webhook events sent by Inkress and their payload structures.

Event Structure

All webhook events follow a consistent structure:

1{
2  "id": "evt_abc123xyz",
3  "event_type": "payment.success",
4  "created_at": "2024-11-26T10:30:00Z",
5  "data": {
6    // Event-specific data
7  },
8  "metadata": {
9    "merchant_id": "mch_123",
10    "environment": "production"
11  }
12}

Payment Events

payment.success

Success

Triggered when a payment is successfully completed and funds are confirmed.

Payload Example

1{
2  "id": "evt_pay_success_123",
3  "event_type": "payment.success",
4  "created_at": "2024-11-26T10:30:00Z",
5  "data": {
6    "transaction_id": "txn_abc123",
7    "order_id": "ord_xyz789",
8    "payment_link_id": "pl_456",
9    "amount": 25000,
10    "currency_code": "JMD",
11    "payment_method": "card",
12    "customer": {
13      "email": "customer@example.com",
14      "first_name": "John",
15      "last_name": "Doe"
16    },
17    "reference_id": "order_1234",
18    "status": "completed"
19  }
20}

Use case: Send order confirmation emails, trigger fulfillment, update inventory, record transaction in your database.

payment.failed

Failed

Triggered when a payment attempt fails due to insufficient funds, declined card, or other issues.

Payload Example

1{
2  "id": "evt_pay_failed_456",
3  "event_type": "payment.failed",
4  "created_at": "2024-11-26T10:35:00Z",
5  "data": {
6    "transaction_id": "txn_def456",
7    "order_id": "ord_xyz789",
8    "payment_link_id": "pl_456",
9    "amount": 25000,
10    "currency_code": "JMD",
11    "payment_method": "card",
12    "failure_reason": "insufficient_funds",
13    "failure_message": "Card declined - insufficient funds",
14    "customer": {
15      "email": "customer@example.com"
16    }
17  }
18}

Use case: Notify customer of payment failure, suggest alternative payment methods, log failed attempts for analytics.

payment.pending

Pending

Triggered when a payment is initiated but awaiting confirmation (e.g., bank transfers).

Use case: Notify customer that payment is being processed, reserve inventory, send payment instructions for bank transfers.

payment.refunded

Refunded

Triggered when a payment is refunded, either partially or fully.

Payload Example

1{
2  "id": "evt_refund_789",
3  "event_type": "payment.refunded",
4  "created_at": "2024-11-26T14:00:00Z",
5  "data": {
6    "transaction_id": "txn_original_123",
7    "refund_id": "rfnd_abc123",
8    "refund_amount": 25000,
9    "original_amount": 25000,
10    "currency_code": "JMD",
11    "reason": "customer_request",
12    "customer": {
13      "email": "customer@example.com"
14    }
15  }
16}

Order Events

order.created

Created

Triggered when a new order is created in the system.

Payload Example

1{
2  "id": "evt_order_created_123",
3  "event_type": "order.created",
4  "created_at": "2024-11-26T10:28:00Z",
5  "data": {
6    "order_id": "ord_xyz789",
7    "reference_id": "order_1234",
8    "total": 25000,
9    "currency_code": "JMD",
10    "status": "pending",
11    "customer": {
12      "email": "customer@example.com",
13      "first_name": "John",
14      "last_name": "Doe",
15      "phone": "+1876-555-0123"
16    },
17    "products": [
18      {
19        "id": 101,
20        "name": "Premium Widget",
21        "quantity": 2,
22        "price": 12500
23      }
24    ],
25    "payment_link_id": "pl_456"
26  }
27}

order.updated

Updated

Triggered when an order's status or details are updated.

Use case: Sync order status changes to your system, update customer on order progress, trigger workflows based on status.

order.fulfilled

Fulfilled

Triggered when an order is marked as fulfilled and shipped to the customer.

Payout Events

payout.created

Created

Triggered when a payout request is submitted.

Payload Example

1{
2  "id": "evt_payout_created_123",
3  "event_type": "payout.created",
4  "created_at": "2024-11-26T11:00:00Z",
5  "data": {
6    "payout_id": "po_abc123",
7    "amount": 50000,
8    "currency_code": "JMD",
9    "type": "standard",
10    "sub_type": 1,
11    "estimated_arrival": "2024-12-03T00:00:00Z",
12    "destination": {
13      "account_number": "****1234",
14      "bank_name": "Example Bank"
15    },
16    "status": "pending"
17  }
18}

payout.processing

Processing

Triggered when a payout request is being processed by the payment provider.

payout.completed

Completed

Triggered when funds have been successfully transferred to the destination account.

Use case: Notify merchant that funds are available, update accounting records, trigger payout confirmation emails.

payout.failed

Failed

Triggered when a payout fails due to invalid bank details or other issues.

Payload Example

1{
2  "id": "evt_payout_failed_456",
3  "event_type": "payout.failed",
4  "created_at": "2024-11-26T12:00:00Z",
5  "data": {
6    "payout_id": "po_def456",
7    "amount": 50000,
8    "currency_code": "JMD",
9    "status": "failed",
10    "failure_reason": "invalid_account",
11    "failure_message": "Bank account number is invalid",
12    "destination": {
13      "account_number": "****5678"
14    }
15  }
16}

Payment Link Events

payment_link.visited

Analytics

Triggered when a customer visits a payment link page.

Use case: Track payment link performance, analyze conversion rates, monitor customer interest.

payment_link.expired

Expired

Triggered when a payment link reaches its expiration date.

Testing Webhook Events

Use the dashboard to send test events to your webhook endpoint:

Go to Settings → Webhooks
Select your webhook endpoint
Click "Send Test Event"
Choose an event type from the list
Review the test payload that will be sent
Click "Send" and verify your endpoint receives it

Tip: Test events are marked with "environment": "test" in the metadata, so you can handle them differently in your code.

← Webhook Setup Webhook Security →