Ir al contenido

Webhooks

Un webhook es una solicitud HTTP que Invoise envía a tu servidor cuando un pago cambia. Puedes empezar con comprobaciones de estado GET y añadir webhooks cuando necesites actualizaciones automáticas.

Ventana de terminal
curl -X POST 'https://platform.invoise.me/api/v1/shops/{shop_id}/webhooks' \
-H 'Authorization: Bearer ivk_...' \
-H 'Idempotency-Key: <saved-unique-key>' \
-H 'Content-Type: application/json' \
-d '{"url":"https://example.com/invoise","filters":["transfer","invoice","payout"]}'

Usa tu propia URL HTTPS pública. Las direcciones locales y privadas se rechazan. Guarda el secret que se devuelve al crear el endpoint: lo necesitas para verificar solicitudes.

Una tienda puede tener hasta 10 endpoints. La URL de un endpoint se puede cambiar, así que reutiliza uno en vez de añadir otro. Consulta Límites.

Evento Significado
transfer.observed Se detectó una transferencia; aún no está confirmada.
transfer.confirmed Una transferencia entrante tiene confirmaciones suficientes. Puede ser solo un pago parcial de la factura.
transfer.reverted Se revirtió un evento de transferencia anterior.
invoice.closed La factura se cerró en la cadena.
invoice.cancelled La página de pago se canceló o la factura caducó; esto no es un reembolso.
payout.sent El pago se transmitió o se detectó su transferencia saliente.
payout.confirmed La contabilidad completa de la liquidación está disponible.
payout.reverted Se revirtió una confirmación de pago anterior.
payout.failed Un fallo terminal del pago necesita intervención.

Para invoice.cancelled, data.reason indica el motivo: expired cuando se agotó la vigencia de la factura, merchant_blocked cuando el personal de Invoise bloqueó el comercio. Una cancelación por parte del comercio, incluida la que causa archivar la tienda, no tiene reason.

Una lista filters vacía recibe todos los eventos. Si no, indica grupos (transfer, invoice, payout), tipos de evento concretos como payout.confirmed, o ambos. Las transferencias entrantes y los pagos salientes son eventos distintos. Un retraso temporal de RPC o de gas no es payout.failed.

gas.wait y sweep.failed se aceptan como filtros, pero Invoise no los envía a tu endpoint. Son señales internas: gas.wait significa que un pago está esperando fondos para la comisión de red y continúa por su cuenta; sweep.failed significa que falló un intento de mover los fondos a tu destinatario. No necesitas actuar en ninguno de los dos casos. Un pago que no puede completarse te llega como payout.failed.

En una tienda sandbox puedes simular ambos mediante POST /shops/{shop_id}/sandbox/simulate para comprobar que un pago retrasado no rompe tu flujo. Solo cambian el estado del pago y no envían ningún webhook.

Invoise-Signature tiene la forma t=<timestamp>,v1=<hex>. La firma es HMAC-SHA256 de timestamp + "." + raw_body, usando tu secreto de webhook.

El siguiente ejemplo en Node.js también rechaza las marcas de tiempo que difieren más de cinco minutos del reloj del servidor. Mantén ese reloj sincronizado y elige tu tolerancia de forma deliberada.

import { createHmac, timingSafeEqual } from 'node:crypto';
export function verify(rawBody, header, secret) {
const match = /^t=(\d+),v1=([a-f0-9]{64})$/.exec(header ?? '');
if (!match) return false;
const [, timestamp, signature] = match;
const age = Math.abs(Date.now() / 1000 - Number(timestamp));
if (!Number.isFinite(age) || age > 300) return false;
const expected = createHmac('sha256', secret)
.update(timestamp + '.')
.update(rawBody)
.digest();
return timingSafeEqual(Buffer.from(signature, 'hex'), expected);
}

Pasa los bytes originales de la solicitud como rawBody. No analices el JSON ni lo conviertas de nuevo en cadena antes de comprobar la firma. Rechaza las firmas no válidas antes de guardar o actuar sobre su contenido.

Así es el cuerpo de transfer.confirmed. El esquema de cada evento está en la sección webhooks de openapi.json.

{
"id": "<event-id>",
"type": "transfer.confirmed",
"created_at": "2026-09-19T10:00:05Z",
"data": {
"issuance_id": "<issuance-id>",
"public_id": "<public-id>",
"shop_id": "<shop-id>",
"external_id": "customer-42",
"type": "deposit",
"family": "evm",
"chain_id": 8453,
"token": "<token-address>",
"token_decimals": 6,
"address": "<payment-address>",
"recipient": "<recipient-address>",
"invoice_cancelled": false,
"cancelled_at": null,
"direction": "incoming",
"chain_event": {
"event_id": "<transfer-id>",
"kind": "transfer.confirmed",
"chain_id": 8453,
"tx_hash": "<tx-hash>",
"log_index": 2,
"block_number": 35123456,
"block_hash": "<block-hash>",
"token": "<token-address>",
"from": "<payer-address>",
"to": "<payment-address>",
"amount": "25000000",
"confirmations": 12,
"occurred_at": "2026-09-19T10:00:00Z"
}
}
}

Para acreditar un pago, lee data.chain_event. amount es lo que llegó, en unidades base del token: divídelo entre 10^data.token_decimals, así que 25000000 con 6 decimales son 25 tokens. event_id identifica la transferencia y tx_hash es su transacción. data.issuance_id y data.external_id indican la factura o el depósito que pagó. En una factura, una transferencia puede ser un pago parcial.

Caso Manejo
Duplicados Evita duplicados usando Invoise-Event-ID, que coincide con el id del sobre. Guarda el ID y la actualización de negocio de forma atómica.
Aceptar un evento Guarda los eventos aceptados de forma duradera, devuelve 2xx con prontitud y procesa el trabajo en cola después.
Reintentos y repeticiones Los reintentos y las repeticiones manuales repiten el ID del evento. Invoise-Attempt-ID cambia y no es una clave de deduplicación.
Cabeceras Cada solicitud lleva Invoise-Event-ID e Idempotency-Key, ambos iguales al id del evento; Invoise-Delivery-ID, uno por evento y endpoint; Invoise-Attempt-ID, nuevo en cada intento; e Invoise-Signature.
Orden de los eventos Los eventos pueden llegar desordenados. Usa su contenido y concilia con el estado actual cuando sea necesario.

Si una reorganización de la cadena elimina una transferencia, llega transfer.reverted con chain_event.reference_event_id igual al event_id de la transferencia que acreditaste: descuenta ese importe. payout.confirmed trae amount, lo que recibió el destinatario, y service_fee, la comisión de ese pago; en payout.sent y payout.failed ambos son null. Cada evento de pago tiene un payout_id estable y el hash de la transacción. incoming_transfer_ids lista las transferencias que cubrió el pago, como máximo 100; incoming_transfers_truncated indica que la lista es más larga.

Los eventos guardados más antiguos pueden usar project_id; lee primero shop_id y recurre a él si es necesario. Las repeticiones conservan los bytes originales.

GET /api/v1/shops/{shop_id}/deposits es el registro completo de las transferencias entrantes confirmadas de la tienda, tanto de facturas como de depósitos, de las más recientes a las más antiguas. No es una lista de direcciones: POST en la misma ruta crea una dirección de depósito. Cada fila tiene id, igual a chain_event.event_id del webhook, además de issuance_id, external_id, amount, tx_hash, sender y occurred_at. Recórrelo con limit y cursor para ponerte al día tras una caída o comprobar tus registros.

status en el registro siempre es confirmed. Una transferencia revertida por una reorganización desaparece del registro y recibes transfer.reverted por ella.

Una entrega tiene éxito cuando tu endpoint responde con cualquier estado 2xx. Otro estado, un tiempo de espera agotado o un error de conexión se reintenta: el primer reintento llega a los 5 segundos y la espera se duplica tras cada intento, hasta una hora como máximo entre intentos. Si en 72 horas no llega un 2xx, Invoise se detiene y marca la entrega como failed.

Cada intento tiene 20 segundos en total, y las cabeceras de tu respuesta deben llegar en 10 segundos. Guarda el evento y responde primero; haz el trabajo después.

Archivar una tienda con PATCH /api/v1/shops/{shop_id} y {"archived":true} deshabilita sus endpoints de webhook. Los eventos de la tienda, incluido el invoice.cancelled de sus facturas sin pagar, se siguen registrando, pero no se entregan.

Lista con GET /api/v1/shops/{shop_id}/deliveries. Repite una entrega con POST /api/v1/shops/{shop_id}/deliveries/{id}/replay y una clave de idempotencia guardada. Repetir no crea un nuevo evento de negocio. Una repetición abre una nueva ventana de reintentos de 72 horas; se puede repetir una entrega entregada o fallida.