Webhooks

​

When to use webhooks

• when you need to react to create, update, or delete events without building change detection around frequent polling,
• when you want to keep a local cache or downstream system in sync only after a real change,
• when you want to separate event reception from the later fetch of the resource detail.

​

Subscription management

• you must store plainTextSecret securely from the create or rotate response,
• changing url or subscribedEvents does not rotate the secret automatically,
• isActive = false does not remove history, it only prevents new deliveries.

​

Endpoint requirements

• url must use https://,
• url must not contain a username or password,
• the hostname must resolve to a public IP address,
• localhost, .local, private ranges, loopback, link-local, and other reserved addresses are rejected by the backend.

​

Delivery payload

{
  "id": "7f4d1861-9f6a-4fa8-a8a7-f335d7a8d515",
  "type": "invoices.updated",
  "occurredAt": "2026-03-18T15:04:05Z",
  "resource": {
    "type": "invoice",
    "id": 301
  }
}

​

Field semantics

• an API version,
• an absolute or relative resource URL,
• a full resource snapshot,
• embedded lookups or nested business objects.

​

Delivery headers

​

Signature verification

1. check that all required webhook headers are present,
2. check that webhook-timestamp is not too old or too far in the future,
3. compute HMAC SHA-256 over the raw request body and compare it in constant time,
4. deduplicate by webhook-id so that retries remain safe to process.

​

Recommended flow

​

Pseudocode

rawBody = read_raw_request_body()
webhookId = header("webhook-id")
timestamp = integer(header("webhook-timestamp"))
providedSignature = header("webhook-signature")

if webhookId is missing or timestamp is missing or providedSignature is missing:
    return 400

if abs(current_unix_time() - timestamp) > 300:
    return 401

expectedSignature = hmac_sha256(rawBody, webhookSecret)

if not constant_time_equals(expectedSignature, providedSignature):
    return 401

if webhook_id_exists_in_dedup_store(webhookId):
    return 204

store_webhook_id(webhookId)
enqueue_fetch_job(parse_json(rawBody))

return 204

​

JavaScript / Node.js-like example

import crypto from 'node:crypto';

export async function handleFintoroWebhook(req, res) {
  // `req.rawBody` must contain the original raw request body before JSON parsing.
  const rawBody = req.rawBody.toString('utf8');
  const webhookId = req.get('webhook-id');
  const timestamp = Number(req.get('webhook-timestamp'));
  const providedSignature = req.get('webhook-signature');

  if (!webhookId || !timestamp || !providedSignature) {
    return res.status(400).json({ error: 'Missing webhook headers.' });
  }

  if (!isFreshWebhookTimestamp(timestamp)) {
    return res.sendStatus(401);
  }

  if (!isValidWebhookSignature(rawBody, providedSignature, process.env.FINTORO_WEBHOOK_SECRET)) {
    return res.sendStatus(401);
  }

  if (await hasProcessedWebhook(webhookId)) {
    return res.sendStatus(204);
  }

  const event = JSON.parse(rawBody);

  await storeWebhookId(webhookId);
  await enqueueFetchWebhookResourceDetail({
    webhookId,
    eventType: event.type,
    resourceType: event.resource.type,
    resourceId: event.resource.id,
    companyId: event.company.id,
  });

  return res.sendStatus(204);
}

function isFreshWebhookTimestamp(timestamp) {
  return Math.abs(Math.floor(Date.now() / 1000) - timestamp) <= 300;
}

function isValidWebhookSignature(rawBody, providedSignature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(rawBody)
    .digest('hex');

  if (expectedSignature.length !== providedSignature.length) {
    return false;
  }

  return crypto.timingSafeEqual(
    Buffer.from(expectedSignature, 'utf8'),
    Buffer.from(providedSignature, 'utf8'),
  );
}

​

How to respond to a delivery

• Return 2xx only after the request has been safely received, verified, and stored for downstream processing.
• If the signature or timestamp is invalid, return 401 or your receiver-specific auth failure.
• If a downstream dependency is temporarily unavailable and you want a retry, return a non-2xx status.
• If you accept the request and only enqueue internal work, 204 No Content is perfectly fine.

• idempotent,
• resilient to duplicates,
• able to return 2xx for an already processed webhook-id.

​

Retry mechanism

• the receiver returns a non-2xx HTTP status,
• the request times out,
• a network-level send error occurs.
• the endpoint no longer passes the pre-send URL, DNS, and IP safety validation.

• never assume exactly-once delivery,
• expect the same webhook-id to arrive more than once,
• respond quickly and move heavier logic to your internal queue,
• return non-2xx only when you actually want Fintoro to retry the delivery.

​

Thin payload and the follow-up detail fetch

1. receive the webhook and verify the signature,
2. deduplicate by webhook-id,
3. determine the correct detail endpoint from type and resource,
4. fetch the resource detail from the Fintoro API version used by your integration,
5. run business logic only on the fetched detail.

• clients.updated + resource.id = 42 → GET /clients/42
• invoices.created + resource.id = 301 → GET /invoices/301
• warehouse-outbound-receipts.deleted + resource.id = 88 → if the detail is already gone, process the delete locally from the event itself

​

Available events

​

Master data

​

CRM

​

Warehouses and catalog

​

Documents

​

Production recommendations

• do not run heavy business logic directly in the receiver HTTP thread,
• persist the raw payload and webhook-id before downstream processing,
• rotate secrets in a controlled way and coordinate rollout with the receiver,
• monitor retry patterns and repeated non-2xx responses as an indicator of a receiver-side incident,
• log webhook-id, type, resource.type, resource.id, and the X-Request-Id from the later resource fetch,
• for delete events, do not assume the detail endpoint can still return the deleted resource.

​

Related sections

• Getting started
• Authentication
• API conventions
• Errors and idempotency
• Webhook API reference