Webhooks

How it works

When webhooks fire

A webhook is created for each of the following invoice transitions:

There are two payload variants depending on whether the customer had already selected a payment method:

• If a payment method was selected, the payload includes deal-related fields such as sub_status, rate_usd, and adjustment fields.
• If the invoice expired or was canceled before method selection, deal-related fields are null or false, and a reason field is included.

Both variants use the same top-level structure, so one parser on your side is enough.

Webhook URL priority

The system uses the destination URL in this order:

1. callback_url supplied in the create-invoice request
2. Default webhook URL configured for the merchant account

If neither is set, no webhook notification is sent.

Payload

Sent as POST with Content-Type: application/json:

{
  "event_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479:success:1714237200",
  "order_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "external_id": "order-2026-0001",
  "status": "success",
  "sub_status": "successfully_paid",
  "finished_at": "2026-04-27T14:35:00+00:00",
  "expires_at": "2026-04-27T14:50:00+00:00",
  "amount": "1500.00",
  "currency": "UAH",
  "rate_usd": "41.20",
  "success_url": "https://ecca-ex.com/order/2026-0001/success",
  "fail_url": "https://ecca-ex.com/order/2026-0001/fail",
  "is_adjusted": false,
  "original_amount": null,
  "adjusted_amount": null
}

For pre-method-selection events, the payload additionally contains "reason": "ttl_expired" or "user_canceled", and sub_status, rate_usd, original_amount, and adjusted_amount are null.

Payload fields

Adjusted amount flow

In some dispute cases, the final invoice amount can be reduced during manual resolution.

When this happens:

• is_adjusted becomes true
• amount contains the final adjusted amount
• original_amount contains the original amount
• adjusted_amount contains the new final amount

Example adjusted webhook

{
  "event_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479:success:1714237200",
  "order_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "external_id": "order-2026-0001",
  "status": "success",
  "sub_status": "completed_with_adjustment",
  "amount": "1200.00",
  "currency": "UAH",
  "is_adjusted": true,
  "original_amount": "1500.00",
  "adjusted_amount": "1200.00",
  "finished_at": "2026-04-27T14:35:00+00:00",
  "rate_usd": "41.20"
}

What your backend should do

• Use amount or adjusted_amount as the final amount in your system
• Keep original_amount only for reference or audit purposes
• Update your local order amount if you store it in your database

Adjustment guarantees

• Adjustments only decrease the amount
• A deal can be adjusted at most once
• Once is_adjusted=true, it remains true
• If no adjustment happened, is_adjusted=false and both original_amount and adjusted_amount are null

Signature verification

Every webhook request includes three headers:

X-Signature: 7c5c2c8a4f9d3e1b...
X-Signature-Timestamp: 1714237200
X-Idempotency-Key: f47ac10b-...:success:1714237200

The signature is computed as:

signature = HMAC_SHA256(
    key   = <your active API key secret>,
    data  = f"{X-Signature-Timestamp}.{raw_request_body}",
).hexdigest()

To verify it, recompute the HMAC on your side and compare it with the header in constant time.

Verification examples

import hmac
import hashlib
import os
from fastapi import FastAPI, Request, HTTPException

app = FastAPI()
API_SECRET = os.environ["MERCHANT_API_SECRET"].encode()

@app.post("/webhooks/payment")
async def handle_webhook(request: Request):
    signature = request.headers.get("X-Signature", "")
    ts = request.headers.get("X-Signature-Timestamp", "")
    event_id = request.headers.get("X-Idempotency-Key", "")

    if not signature or not ts or not event_id:
        raise HTTPException(403, "Missing signature headers")

    raw = await request.body()
    expected = hmac.new(
        API_SECRET,
        f"{ts}.".encode() + raw,
        hashlib.sha256,
    ).hexdigest()

    if not hmac.compare_digest(expected, signature):
        raise HTTPException(403, "Bad signature")

    if await already_processed(event_id):
        return {"ok": True}

    payload = await request.json()
    await enqueue_for_processing(event_id, payload)
    return {"ok": True}

import crypto from "node:crypto";
import express from "express";

const app = express();
const API_SECRET = process.env.MERCHANT_API_SECRET;

app.post(
  "/webhooks/payment",
  express.raw({ type: "application/json" }),
  async (req, res) => {
    const signature = req.headers["x-signature"] ?? "";
    const ts = req.headers["x-signature-timestamp"] ?? "";
    const eventId = req.headers["x-idempotency-key"] ?? "";

    if (!signature || !ts || !eventId) {
      return res.status(403).json({ error: "Missing signature headers" });
    }

    const expected = crypto
      .createHmac("sha256", API_SECRET)
      .update(`${ts}.`)
      .update(req.body)
      .digest("hex");

    const a = Buffer.from(expected, "hex");
    const b = Buffer.from(signature, "hex");
    if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) {
      return res.status(403).json({ error: "Bad signature" });
    }

    if (await alreadyProcessed(eventId)) {
      return res.json({ ok: true });
    }

    const payload = JSON.parse(req.body.toString("utf8"));
    await enqueueForProcessing(eventId, payload);
    res.json({ ok: true });
  },
);

<?php
$apiSecret = getenv('MERCHANT_API_SECRET');
$signature = $_SERVER['HTTP_X_SIGNATURE'] ?? '';
$ts = $_SERVER['HTTP_X_SIGNATURE_TIMESTAMP'] ?? '';
$eventId = $_SERVER['HTTP_X_IDEMPOTENCY_KEY'] ?? '';

if ($signature === '' || $ts === '' || $eventId === '') {
    http_response_code(403);
    exit(json_encode(['error' => 'Missing signature headers']));
}

$raw = file_get_contents('php://input');
$expected = hash_hmac('sha256', $ts . '.' . $raw, $apiSecret);

if (!hash_equals($expected, $signature)) {
    http_response_code(403);
    exit(json_encode(['error' => 'Bad signature']));
}

if (already_processed($eventId)) {
    echo json_encode(['ok' => true]);
    exit;
}

$payload = json_decode($raw, true);
enqueue_for_processing($eventId, $payload);
echo json_encode(['ok' => true]);

Optional: timestamp freshness window

If your security model genuinely requires it, you can add a freshness check — but pick a window much larger than the retry schedule, otherwise legitimate retries get dropped:

import time

MAX_SKEW_SEC = 24 * 60 * 60

if abs(time.time() - int(ts)) > MAX_SKEW_SEC:
    raise HTTPException(403, "Stale timestamp")

For most merchants the safer choice is to skip this check entirely and rely on event_id deduplication.

Retry policy

If delivery fails because of a non-2xx response, connection error, or timeout, the system retries automatically.

There are 7 automatic retry attempts with escalating delays:

After all automatic retries fail, the event is marked as dead and no further automatic delivery is performed.

Event lifecycle

Webhook management API

Use the webhook management API to inspect delivery history and manually resend the latest webhook event for an invoice.

All endpoints require your merchant API key:

X-Api-Key: <your_merchant_api_key>

invoice_ref can be either:

• order_id — platform invoice UUID
• external_id — your order ID supplied at invoice creation

Get webhook history

GET /api/v1/invoices/order-2026-0001/webhooks HTTP/1.1
Host: api.ecca-ex.com
X-Api-Key: <your_merchant_api_key>

Example response:

{
  "successful": true,
  "invoice_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "external_id": "order-2026-0001",
  "events_count": 1,
  "events": [
    {
      "event_id": 123,
      "event_type": "invoice.success",
      "status": "success",
      "callback_url": "https://ecca-ex.com/webhooks/payment",
      "auto_attempts": 1,
      "manual_attempts": 0,
      "total_attempts": 1,
      "next_retry_at": null,
      "locked_at": null,
      "locked_by": null,
      "request_payload": {
        "event_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479:success:1714237200",
        "order_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
        "external_id": "order-2026-0001",
        "status": "success",
        "sub_status": "successfully_paid",
        "amount": "1500.00",
        "currency": "UAH",
        "is_adjusted": false
      },
      "created_at": "2026-04-27T14:35:00+00:00",
      "updated_at": "2026-04-27T14:35:02+00:00",
      "attempts": [
        {
          "try_number": 1,
          "trigger": "auto",
          "attempt_status": "success",
          "http_status": 200,
          "response_headers": {
            "content-type": "application/json"
          },
          "response_body": "{"ok":true}",
          "error_message": null,
          "duration_ms": 184,
          "created_at": "2026-04-27T14:35:02+00:00"
        }
      ]
    }
  ]
}

Webhook history fields

Resend latest webhook via API

POST /api/v1/invoices/order-2026-0001/webhooks/resend HTTP/1.1
Host: api.ecca-ex.com
X-Api-Key: <your_merchant_api_key>

Example response:

{
  "successful": true,
  "invoice_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "event_id": 123,
  "resend": {
    "ok": true,
    "http_status": 200,
    "duration_ms": 176,
    "attempt_id": 456
  }
}

Resend behavior

• Resends the latest webhook event for the invoice
• Works for events in pending, success, or dead status
• Creates a new delivery attempt with trigger=manual
• Does not modify the automatic retry schedule
• A successful manual resend changes the event status to success
• A cooldown is enforced between manual resend attempts for the same event

Timeout

Each delivery attempt has a 15-second timeout.

If your endpoint does not return a response within that time, the attempt is marked as failed and retried automatically.

Best practices

• Verify the signature using the raw request body and constant-time comparison
• Reject requests with missing, malformed, or invalid signature data
• Treat amount as the source of truth when is_adjusted=true
• Respond within 15 seconds
• Deduplicate events using event_id or X-Idempotency-Key
• Use the webhook history API to inspect delivery attempts and callback responses
• Use the resend API when you need to trigger the latest webhook again
• Log request headers and raw request body for easier debugging