Webhook Events Reference

Complete list of all webhook events you can subscribe to.

Overview

Webhooks allow your application to receive real-time notifications when events occur in AuxVault. Instead of polling for changes, AuxVault sends HTTP POST requests to your configured endpoint.

Event Structure

All webhook events follow this structure:

{
  "id": "evt_abc123",
  "type": "transaction.approved",
  "timestamp": "2026-01-28T12:34:56Z",
  "data": {
    ...event-specific data...
  },
  "tenantId": "your-tenant-id",
  "merchantId": "merchant_123"
}

💳 Transaction Events

transaction.approved

Sent when a transaction is approved.

{
  "type": "transaction.approved",
  "data": {
    "transactionId": "txn_abc123",
    "type": "sale",
    "amount": 150.00,
    "currency": "USD",
    "authCode": "123456",
    "card": {
      "brand": "Visa",
      "last4": "1111"
    },
    "customer": {
      "email": "customer@example.com"
    }
  }
}

When fired: Immediately after transaction approval

transaction.declined

Sent when a transaction is declined.

{
  "type": "transaction.declined",
  "data": {
    "transactionId": "txn_declined_456",
    "type": "sale",
    "amount": 150.00,
    "declineReason": "Insufficient funds",
    "declineCode": "insufficient_funds",
    "card": {
      "brand": "Visa",
      "last4": "1111"
    }
  }
}

When fired: Immediately after transaction decline

transaction.voided

Sent when a transaction is voided.

{
  "type": "transaction.voided",
  "data": {
    "transactionId": "txn_abc123",
    "voidedAt": "2026-01-28T13:00:00Z",
    "voidedBy": "user_123"
  }
}

When fired: Immediately after void

transaction.captured

Sent when an authorized transaction is captured.

{
  "type": "transaction.captured",
  "data": {
    "transactionId": "txn_abc123",
    "authorizedAmount": 150.00,
    "capturedAmount": 120.00,
    "capturedAt": "2026-01-28T14:00:00Z"
  }
}

When fired: Immediately after capture

💰 Refund Events

refund.approved

Sent when a refund is approved.

{
  "type": "refund.approved",
  "data": {
    "refundId": "ref_xyz789",
    "transactionId": "txn_abc123",
    "amount": 75.00,
    "currency": "USD",
    "reason": "Customer request",
    "refundedAt": "2026-01-28T15:00:00Z"
  }
}

When fired: Immediately after refund approval

refund.declined

Sent when a refund is declined.

{
  "type": "refund.declined",
  "data": {
    "refundId": "ref_declined_123",
    "transactionId": "txn_abc123",
    "amount": 75.00,
    "declineReason": "Account closed",
    "declineCode": "R02"
  }
}

When fired: Immediately after refund decline

🔁 Recurring Billing Events

subscription.created

Sent when a subscription is created.

{
  "type": "subscription.created",
  "data": {
    "subscriptionId": "sub_abc123",
    "customerId": "cust_456",
    "planId": "plan_monthly",
    "amount": 99.00,
    "frequency": "monthly",
    "startDate": "2026-01-28",
    "nextBillingDate": "2026-02-28"
  }
}

When fired: Immediately after subscription creation

subscription.payment_succeeded

Sent when a subscription payment succeeds.

{
  "type": "subscription.payment_succeeded",
  "data": {
    "subscriptionId": "sub_abc123",
    "transactionId": "txn_payment_789",
    "amount": 99.00,
    "billingDate": "2026-01-28",
    "nextBillingDate": "2026-02-28"
  }
}

When fired: Immediately after successful recurring payment

subscription.payment_failed

Sent when a subscription payment fails.

{
  "type": "subscription.payment_failed",
  "data": {
    "subscriptionId": "sub_abc123",
    "amount": 99.00,
    "attemptCount": 1,
    "declineReason": "Insufficient funds",
    "nextRetryDate": "2026-01-30"
  }
}

When fired: Immediately after failed recurring payment

subscription.cancelled

Sent when a subscription is cancelled.

{
  "type": "subscription.cancelled",
  "data": {
    "subscriptionId": "sub_abc123",
    "cancelledAt": "2026-01-28T16:00:00Z",
    "cancelledBy": "user_123",
    "reason": "Customer request"
  }
}

When fired: Immediately after cancellation

subscription.paused

Sent when a subscription is paused.

{
  "type": "subscription.paused",
  "data": {
    "subscriptionId": "sub_abc123",
    "pausedAt": "2026-01-28T17:00:00Z",
    "pausedBy": "user_123"
  }
}

When fired: Immediately after pause

subscription.resumed

Sent when a subscription is resumed.

{
  "type": "subscription.resumed",
  "data": {
    "subscriptionId": "sub_abc123",
    "resumedAt": "2026-01-28T18:00:00Z",
    "nextBillingDate": "2026-02-28"
  }
}

When fired: Immediately after resume

📄 Invoice Events

invoice.created

Sent when an invoice is created.

{
  "type": "invoice.created",
  "data": {
    "invoiceId": "inv_abc123",
    "customerId": "cust_456",
    "amount": 500.00,
    "dueDate": "2026-02-15",
    "status": "draft"
  }
}

When fired: Immediately after invoice creation

invoice.sent

Sent when an invoice is sent to customer.

{
  "type": "invoice.sent",
  "data": {
    "invoiceId": "inv_abc123",
    "sentAt": "2026-01-28T19:00:00Z",
    "sentVia": ["email", "sms"],
    "customer": {
      "email": "customer@example.com",
      "phone": "+1234567890"
    }
  }
}

When fired: After invoice is sent

invoice.paid

Sent when an invoice is fully paid.

{
  "type": "invoice.paid",
  "data": {
    "invoiceId": "inv_abc123",
    "transactionId": "txn_payment_123",
    "amount": 500.00,
    "paidAt": "2026-01-29T10:00:00Z"
  }
}

When fired: After full payment received

invoice.payment_received

Sent when a partial payment is received.

{
  "type": "invoice.payment_received",
  "data": {
    "invoiceId": "inv_abc123",
    "transactionId": "txn_partial_456",
    "paymentAmount": 200.00,
    "remainingBalance": 300.00
  }
}

When fired: After each payment (partial or full)

invoice.overdue

Sent when an invoice becomes overdue.

{
  "type": "invoice.overdue",
  "data": {
    "invoiceId": "inv_abc123",
    "dueDate": "2026-02-15",
    "daysOverdue": 5,
    "amount": 500.00
  }
}

When fired: Daily check at midnight for overdue invoices

invoice.cancelled

Sent when an invoice is cancelled.

{
  "type": "invoice.cancelled",
  "data": {
    "invoiceId": "inv_abc123",
    "cancelledAt": "2026-01-30T11:00:00Z",
    "reason": "Customer request"
  }
}

When fired: Immediately after cancellation

💰 Settlement Events

settlement.created

Sent when a settlement is created.

{
  "type": "settlement.created",
  "data": {
    "settlementId": "stl_abc123",
    "merchantId": "merchant_123",
    "amount": 10000.00,
    "transactionCount": 50,
    "settlementDate": "2026-01-30"
  }
}

When fired: When settlement batch is generated

settlement.paid

Sent when settlement funds are disbursed.

{
  "type": "settlement.paid",
  "data": {
    "settlementId": "stl_abc123",
    "amount": 10000.00,
    "paidAt": "2026-01-30T10:00:00Z",
    "bankAccount": {
      "last4": "5678"
    }
  }
}

When fired: When funds are sent to merchant account

🛡️ Fraud Events

fraud.alert

Sent when suspicious activity is detected.

{
  "type": "fraud.alert",
  "data": {
    "transactionId": "txn_suspicious_123",
    "riskScore": 85,
    "riskFactors": [
      "Multiple declined attempts",
      "IP address mismatch"
    ],
    "action": "flagged_for_review"
  }
}

When fired: When fraud detection rules trigger

🔧 Advanced Events

refund_decline_queue.created

Sent when a refund is added to decline queue.

{
  "type": "refund_decline_queue.created",
  "data": {
    "id": "rdq_abc123",
    "transactionId": "txn_456",
    "amount": 150.75,
    "declineReason": "Account closed",
    "scheduledRetryAt": "2026-01-28T15:05:00Z"
  }
}

When fired: When refund is declined and queued

refund_decline_queue.resolved

Sent when a declined refund is successfully processed.

{
  "type": "refund_decline_queue.resolved",
  "data": {
    "id": "rdq_abc123",
    "transactionId": "txn_456",
    "amount": 150.75,
    "attemptCount": 3,
    "resolvedAt": "2026-01-28T16:00:00Z"
  }
}

When fired: When retry succeeds or manual resolution

refund_decline_queue.failed

Sent when all retry attempts exhausted.

{
  "type": "refund_decline_queue.failed",
  "data": {
    "id": "rdq_abc123",
    "transactionId": "txn_456",
    "amount": 150.75,
    "attemptCount": 3,
    "lastError": "Account closed"
  }
}

When fired: After max retry attempts reached

📊 Batch Events

batch.created

Sent when a batch is created.

{
  "type": "batch.created",
  "data": {
    "batchId": "batch_abc123",
    "merchantId": "merchant_123",
    "transactionCount": 25,
    "totalAmount": 5000.00
  }
}

When fired: When batch is generated

batch.settled

Sent when a batch is settled.

{
  "type": "batch.settled",
  "data": {
    "batchId": "batch_abc123",
    "settledAt": "2026-01-29T00:00:00Z",
    "status": "settled"
  }
}

When fired: When batch settlement completes

Webhook Delivery

Headers Sent

POST /your-webhook-url
Content-Type: application/json
X-Luqra-Signature: sha256=abc123...
X-Luqra-Event: transaction.approved
X-Luqra-Timestamp: 2026-01-28T12:34:56Z

Retry Logic

Initial attempt: Immediate
Retry 1: After 5 minutes
Retry 2: After 15 minutes
Retry 3: After 1 hour
Retry 4: After 6 hours
Retry 5: After 24 hours

After 5 failed attempts, the webhook is marked as failed.

Expected Response

Your endpoint should return a 2xx status code within 5 seconds:

HTTP/1.1 200 OK

Best Practices

✅ DO:

Verify signatures - Ensure webhooks are from AuxVault
Respond quickly - Return 200 within 5 seconds
Process async - Queue webhook for processing
Handle duplicates - Use event ID for idempotency
Log all events - For debugging and audit trail
Test thoroughly - Use sandbox webhooks

❌ DON'T:

Don't do heavy processing - Respond quickly, process later
Don't ignore signatures - Always verify
Don't skip error handling - Handle all scenarios
Don't expose endpoint - Use HTTPS and authentication
Don't retry synchronously - We handle retries

Testing Webhooks

Test Event Endpoint

Trigger test webhooks:

curl -X POST https://dev.auxcore.net/api/v1/webhooks/webhook_123/test \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Tenant-ID: your-tenant-id" \
  -d '{
    "eventType": "transaction.approved"
  }'

Next Steps

Need help? Contact support@auxvault.com