Accept Tochka webhook (JWT) and dispatch stored callback payload

What it does

• Accepts Tochka bank webhook as a JWT string (body may be plain or base64-encoded)
• Verifies the JWT signature against Tochka public JWK
• Extracts operationId from payload and loads the invoice from @dieugene/payments-db
• Sends a POST request to the stored callback URL with stored payload

Install

npm i @dieugene/tochka-webhook-dispatcher

Requirements

• Node.js >= 18 (built-in fetch is used)
• Environment variable PAYMENTS_DB_ADDRESS must be set for @dieugene/payments-db

Input formats

handler(input) accepts any of the following:

• String: the JWT string
• Buffer: the JWT in a Buffer
• Object with { body, isBase64Encoded } fields (e.g., AWS/GCP/serverless)
• Fetch Request-like object with a text() method (e.g., Cloudflare/Vercel)

If isBase64Encoded === true, body will be decoded from base64 before verification.

Minimal usage (serverless HTTP handler)

const { handler } = require('@dieugene/tochka-webhook-dispatcher');

module.exports.handler = async (event) => {
  return await handler({ body: event.body, isBase64Encoded: event.isBase64Encoded });
};

Expected JWT payload structure

After verification/decoding, the module expects one of the following shapes (actual payload from Tochka):

• { Data: { operationId: string, ... } }
• { operationId: string, ... }

operationId is used to look up the invoice in the database.

Database contract (@dieugene/payments-db)

The invoice is read by id/uuid equal to operationId. The dispatcher expects the invoice to contain:

{
  "data": {
    "callback_data": {
      "url": "https://example.com/callback",
      "payload": { "any": "json" }
    }
  }
}

• url: destination endpoint
• payload: JSON body sent as-is

Return value

The handler always returns HTTP 200 with a JSON body describing dispatch result.

On success:

{ statusCode: 200, body: { dispatched: true, invoice_id: "<id>", reason: "" } }

If a callback cannot be dispatched:

{ statusCode: 200, body: { dispatched: false, reason: "<reason>" } }

Possible reasons:

• no_invoice_ident — no operationId in payload
• invoice_not_found — invoice missing in DB
• no_callback_url — callback URL is absent
• no_global_fetch — global fetch is not available

Optional configuration

By default, the public JWK is fetched from: https://enter.tochka.com/doc/openapi/static/keys/public

You may override via options if you call lower-level functions directly (decode_webhook, etc.).

Notes

• The module does not add retries or extra validation. It is minimal by design.
• Ensure PAYMENTS_DB_ADDRESS is configured and reachable at runtime.