Webhooks

Webhooks allow you to receive real-time notifications when events occur in your Dimebia account.

Overview

Webhooks are HTTP callbacks triggered by events. Dimebia sends a POST request to your configured endpoint when specific events occur.

Supported Events

Transaction Events

Event	Description
transaction.created	A new transaction was created
transaction.processing	Transaction is being processed
transaction.succeeded	Payment completed successfully
transaction.failed	Payment failed
transaction.refunded	Transaction was refunded
transaction.cancelled	Transaction was cancelled

Subscription Events

Event	Description
subscription.created	New subscription created
subscription.updated	Subscription was modified
subscription.cancelled	Subscription was cancelled
subscription.expired	Subscription expired
invoice.paid	Invoice was paid
invoice.payment_failed	Invoice payment failed

Configure Webhooks

POST /api/webhook/register

{
  "url": "https://your-domain.com/webhooks/dimebia",
  "events": [
    "transaction.succeeded",
    "transaction.failed",
    "invoice.paid"
  ],
  "secret": "your-webhook-secret"
}

Webhook Payload

{
  "id": "evt_1234567890",
  "type": "transaction.succeeded",
  "created": 1724000000,
  "data": {
    "object": {
      "id": "TXN2026081800001",
      "amount": 100000,
      "currency": "USD",
      "status": "SUCCESS",
      "createdTime": "2026-08-18T10:00:00Z"
    }
  }
}

Webhook Headers

Header	Description
X-Dimebia-Signature	HMAC-SHA256 signature for verification
X-Dimebia-Event	Event type
X-Dimebia-Delivery	Unique delivery ID
Content-Type	application/json

Verify Webhook Signatures

Always verify webhook signatures:

import crypto from 'crypto';

function verifyWebhook(payload: string, signature: string, secret: string): boolean {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

Retry Policy

• Retry count: 3 attempts
• Retry interval: 1 minute, 5 minutes, 30 minutes
• Timeout: 10 seconds per attempt

Best Practices

1. Respond quickly: Return 200 OK within 10 seconds
2. Queue processing: Process webhooks asynchronously
3. Handle duplicates: Use the delivery ID to deduplicate
4. Verify signatures: Always verify webhook signatures