Developer guide

​

Idempotency

• Use a UUID v4 or a unique business identifier (e.g. your internal order ID)
• Maximum length: 255 characters
• The plugin scopes each key to the effective organization. The same key from two organizations counts as two distinct requests.
• The plugin replays a successful response for 7 days. A replay carries the same status code and body, plus the header X-Idempotency-Replayed: true.
• A 4xx answer does not spend the key: fix the request and send it again under the same key.
• After a 5xx answer the outcome is unknown: read the resource first, and send the request again only under a new key. A key that the answer fenced (X-Idempotency-Fenced: true) is refused with 422 BTF-0014. A 503 BTF-9000 or 503 BTF-9017 ran nothing: send it again under the same key.
• The same key with a different body is refused with 422 BTF-0017. A resend while the first request still runs gets 409 BTF-0016 with Retry-After.
• Every idempotency refusal states its remedy in detail. Read it before you resend.

POST /v1/transfers/initiate
X-Organization-Id: 019c9ac2-3f5d-7df9-9215-bdccc1451def
X-Idempotency: 7f3d9a1b-4e2c-4f8a-b3d1-9e6f2a4c8b7e

​

Duplicate detection

• senderAccountId
• recipient details (ISPB, branch, account, holder document)
• amount
• purpose

​

Retry strategy

​

State handling

​

TED OUT state machine

​

Initiation state machine

​

TED IN state machine

​

P2P state machine

​

Polling vs. webhooks

​

Webhook integration

​

Signature validation

• X-Webhook-Signature: versioned HMAC-SHA256 signature in the form v1,sha256=<hex>
• X-Webhook-Timestamp: Unix timestamp in seconds (UTC) when the plugin built the request
• X-Webhook-Event: the event type (for example, transfer.completed). This header is not part of the signature.

X-Webhook-Signature: v1,sha256=hex(HMAC_SHA256(signingSecret, "v1:" + <timestamp> + "." + <raw_body>))

1. Read X-Webhook-Signature and X-Webhook-Timestamp from the request headers.
2. Build the signed string: "v1:" + timestamp + "." + rawBody.
3. Compute HMAC-SHA256 over the signed string with the signingSecret of the webhook registration, then hex-encode the result.
4. Prepend v1,sha256=, then compare against X-Webhook-Signature with a constant-time equality function.
5. Reject the request if the timestamp is outside an acceptable freshness window (a 5-minute tolerance is typical) to prevent replay.

const crypto = require('crypto');
const express = require('express');

const TOLERANCE_SECONDS = 300; // 5 minutes

function validateWebhook(rawBody, timestamp, signature, secret) {
  if (!timestamp || !signature) return false;

  const ageSeconds = Math.abs(Math.floor(Date.now() / 1000) - parseInt(timestamp, 10));
  if (Number.isNaN(ageSeconds) || ageSeconds > TOLERANCE_SECONDS) return false;

  const signedPayload = Buffer.concat([
    Buffer.from('v1:', 'utf8'),
    Buffer.from(timestamp, 'utf8'),
    Buffer.from('.', 'utf8'),
    rawBody,
  ]);

  const expected = 'v1,sha256=' + crypto
    .createHmac('sha256', secret)
    .update(signedPayload)
    .digest('hex');

  const expectedBuf = Buffer.from(expected);
  const receivedBuf = Buffer.from(signature);
  if (expectedBuf.length !== receivedBuf.length) return false;

  return crypto.timingSafeEqual(expectedBuf, receivedBuf);
}

// Use raw body — not req.body (parsed JSON)
app.post('/webhooks/ted',
  express.raw({ type: 'application/json' }),
  (req, res) => {
    const timestamp = req.headers['x-webhook-timestamp'];
    const signature = req.headers['x-webhook-signature'];

    if (!validateWebhook(req.body, timestamp, signature, process.env.TED_WEBHOOK_SIGNING_SECRET)) {
      return res.status(401).send('Invalid signature');
    }

    const payload = JSON.parse(req.body.toString());
    // process payload...
    res.status(200).send('OK');
  }
);

import hmac
import hashlib
import time

TOLERANCE_SECONDS = 300  # 5 minutes

def validate_webhook(raw_body: bytes, timestamp: str, signature: str, secret: str) -> bool:
    if not timestamp or not signature:
        return False

    try:
        age = abs(int(time.time()) - int(timestamp))
    except ValueError:
        return False
    if age > TOLERANCE_SECONDS:
        return False

    signed_payload = b"v1:" + timestamp.encode() + b"." + raw_body
    expected = "v1,sha256=" + hmac.new(
        secret.encode(),
        signed_payload,
        hashlib.sha256,
    ).hexdigest()

    return hmac.compare_digest(expected, signature)

import (
    "crypto/hmac"
    "crypto/sha256"
    "encoding/hex"
    "strconv"
    "time"
)

const toleranceSeconds = 300 // 5 minutes

func validateWebhook(rawBody []byte, timestamp, signature, secret string) bool {
    if timestamp == "" || signature == "" {
        return false
    }

    ts, err := strconv.ParseInt(timestamp, 10, 64)
    if err != nil {
        return false
    }
    if diff := time.Now().Unix() - ts; diff < -toleranceSeconds || diff > toleranceSeconds {
        return false
    }

    mac := hmac.New(sha256.New, []byte(secret))
    mac.Write([]byte("v1:"))
    mac.Write([]byte(timestamp))
    mac.Write([]byte("."))
    mac.Write(rawBody)
    expected := "v1,sha256=" + hex.EncodeToString(mac.Sum(nil))

    return hmac.Equal([]byte(expected), []byte(signature))
}

​

Idempotent webhook processing

const alreadyProcessed = await db.webhookEvents.exists({
  transferId: payload.transferId,
  event: req.headers['x-webhook-event'],
});

if (alreadyProcessed) {
  return res.status(200).send('OK'); // acknowledge without reprocessing
}

​

Error handling patterns

{
  "type": "https://errors.lerian.studio/v1/BTF-0010",
  "title": "Unprocessable Entity",
  "status": 422,
  "detail": "transfers can only be initiated Monday-Friday between 06:30 and 17:00 America/Sao_Paulo time",
  "instance": "4bf92f3577b34da6a3ce929d0e0e4736",
  "code": "BTF-0010",
  "requestId": "6d3e2a68-1f2b-4c3d-9e4f-5a6b7c8d9e0f",
  "service": "plugin",
  "category": "deterministic",
  "currentTime": "2026-01-21T18:30:00-03:00",
  "nextAvailableTime": "2026-01-22T06:30:00-03:00",
  "openTime": "06:30",
  "closeTime": "17:00",
  "timezone": "America/Sao_Paulo"
}

​

Go-live checklist

• Send X-Idempotency on every initiate, process, and cancel request
• Retry logic implemented with exponential backoff for 5xx/503 errors
• Webhook endpoint deployed and returning 200 within 5 seconds
• Signature validation active on the webhook endpoint
• Webhook event deduplication implemented using transferId + event
• Operating hours validated client-side before calling initiate (reduces unnecessary 422s)
• Both transferId and confirmationNumber stored for reconciliation
• Terminal states (COMPLETED, REJECTED, FAILED, CANCELLED) handled in UI
• Initiation expiry handled (expiresAt): prompt the user to restart when it passes
• Service readiness monitored in your alerting system for BYOC deployments
• Redis reachable and monitored: the service rejects requests when Redis is down
• PLUGIN_AUTH_ENABLED=true configured in production, with a valid PLUGIN_AUTH_ADDRESS (HTTPS)