ZahlenwerkDocs

Webhooks

Notifique automáticamente a sus propios sistemas sobre nuevos informes, documentos y posiciones.

Los webhooks envían una solicitud HTTP a su propio sistema cuando ocurren ciertos eventos, por ejemplo a un data warehouse o a una herramienta de automatización.

Los propietarios y administradores del equipo pueden configurarlos en ConfiguraciónIntegracionesWebhooksConfigurar: ingrese la URL del endpoint y la Descripción (opcional), y luego haga clic en Agregar webhook.

A continuación, Zahlenwerk muestra el secreto de firma (empieza con whsec_) una sola vez. Cópielo de inmediato en su sistema.

Eventos

EventoCuándo
report.parsedUn informe se leyó correctamente.
report.failedFalló la lectura de un informe.
document.extractedSe leyó un aviso de llamada de capital o un estado de cuenta de capital, incluida una nueva lectura.
position.createdSe creó una posición, en la aplicación, en el chat o mediante un cliente de IA.

En Eventos elige qué eventos recibe un webhook. Si no elige ninguno, recibe todos, incluidos los que se agreguen más adelante.

Cuerpo de la solicitud

El cuerpo es JSON. El encabezado Zahlenwerk-Event indica el evento.

{
  "event": "report.parsed",
  "occurred_at": "2026-10-08T09:30:00.000Z",
  "organization_id": "…",
  "data": {
    "report_id": "…",
    "collection_id": "…",
    "collection_name": "…",
    "resource": "zahlenwerk://report/…"
  }
}

data por evento:

EventoCampos en data
report.parsedreport_id, collection_id, collection_name, resource
report.failedreport_id, collection_id, collection_name, error (motivo legible, como máximo 500 caracteres), resource
document.extracteddocument_id, document_type, position_id, position_ids (un estado de cuenta puede abarcar varias posiciones)
position.createdposition_id, instrument_type, name

Verificar la firma

Cada solicitud lleva el encabezado:

Zahlenwerk-Signature: t=<unix-time>,v1=<signature>

v1 es un HMAC-SHA256 sobre "<t>.<body>", con el secreto de su webhook como clave. Verifique la firma y rechace las solicitudes con más de cinco minutos de antigüedad.

import { createHmac, timingSafeEqual } from 'node:crypto';

export function verify(header: string, body: string, secret: string) {
  const parts = Object.fromEntries(header.split(',').map((p) => p.split('=')));
  const expected = createHmac('sha256', secret).update(`${parts.t}.${body}`).digest('hex');
  const fresh = Math.abs(Date.now() / 1000 - Number(parts.t)) < 300;
  const given = Buffer.from(parts.v1 ?? '');
  return fresh && given.length === expected.length && timingSafeEqual(Buffer.from(expected), given);
}

Entrega

  • Cualquier respuesta distinta de 2xx cuenta como fallo, incluidas las 4xx.
  • Si su sistema no responde en 10 segundos, la entrega se considera fallida.
  • Las redirecciones (3xx) no se siguen y cuentan como fallos.
  • Zahlenwerk reintenta las entregas fallidas hasta cuatro veces, con intervalos crecientes. Su sistema debe tolerar solicitudes duplicadas.

Requisitos

  • Solo endpoints HTTPS.
  • Se rechazan las direcciones internas y privadas.

No existe una API REST general. Para acceso de lectura y escritura, use el endpoint MCP.

En esta página

Iniciar sesión
ES
EnglishDeutschEspañol