Webhooks
Remolom te manda un POST firmado cuando pasa algo en tus eventos o entradas: publicaciones, cambios, ventas, reembolsos y validaciones en puerta.
Crear un webhook
En Mi empresa → Webhooks añade la URL (https y pública), elige los tipos de evento y el modo (Real o Prueba). Al crearlo verás el secreto whsec_… una sola vez: guárdalo para verificar la firma. Puedes rotarlo cuando quieras; el anterior deja de valer al momento.
También por API, con el scope webhooks:manage:
| Ruta | Respuesta |
|---|---|
GET /v1/webhooks | { webhooks: [{ id, url, events, active, mode, createdAt, failingSince }] } |
POST /v1/webhooks { url, events, mode? } | { webhook, secret } |
PATCH /v1/webhooks/:id { url?, events?, active? } | { webhook } |
DELETE /v1/webhooks/:id | { ok: true } |
POST /v1/webhooks/:id/rotate | { webhook, secret } |
POST /v1/webhooks/:id/test | { ok, code, error }: envía un ping al momento |
GET /v1/webhooks/:id/deliveries | Las 50 últimas entregas con su estado, intentos y último código |
Máximo 10 webhooks por empresa. Los endpoints de prueba solo reciben sucesos de prueba (de claves rk_test_) y los reales solo los reales.
Qué recibes
POST a tu URL con Content-Type: application/json y estas cabeceras:
| Cabecera | Valor |
|---|---|
Remolom-Signature | t=<unix>,v1=<hex> |
Remolom-Event | El tipo, por ejemplo ticket.sold |
Remolom-Delivery | Id de esta entrega |
User-Agent | Remolom-Webhooks/1.0 |
Cuerpo: { id, type, createdAt, test, data }. El id es el mismo en todos los reintentos del mismo suceso: úsalo para deduplicar.
Tipos de evento
| Tipo | Cuándo | data |
|---|---|---|
event.created | Se crea un evento (web, app, API, MCP, importador o feed) | { event: EventDTO } |
event.updated | Cambia algún dato, se reactiva un cancelado o moderación lo vuelve a publicar | { event: EventDTO } |
event.cancelled | El organizador lo cancela (también DELETE /v1/… o si desaparece de un feed) | { event: EventDTO } |
event.hidden | Moderación de Remolom lo retira | { event: EventDTO } |
ticket.sold | Un pedido se paga (o se reserva gratis) | TicketData con todas las entradas del pedido |
ticket.refunded | Se reembolsa un pedido | TicketData con las entradas anuladas |
ticket.transferred | El titular transfiere una entrada | TicketData con esa entrada y el nuevo holderName |
ticket.checked_in | Se valida en puerta (también lecturas sin conexión al sincronizar) | TicketData con esa entrada |
ping | Botón Enviar prueba o POST …/test | { message, webhookId } |
TicketData = { eventId, orderId, tickets: [{ id, priceId, priceName, holderName, checkedInAt, gate, transferredAt, voidedAt, createdAt }] }. No lleva emails: los datos del comprador se piden con GET /v1/events/:id/tickets.
event.created, event.updated, event.cancelled y event.hidden
{
"id": "6f1c2a…", "type": "event.created", "createdAt": "2026-11-14T10:00:00.000Z", "test": false,
"data": { "event": { "id": "3f0b…", "title": "Concierto de jazz", "status": "published", "startsAt": "2026-12-05T20:00:00.000Z", "externalId": "jazz-2026-12-05", "source": "mi-web", "test": false } }
}En event.cancelled y event.hidden el evento llega con "status": "cancelled". El EventDTO es el mismo de la API (aquí recortado).
ticket.sold
{
"id": "9b2e…", "type": "ticket.sold", "createdAt": "2026-11-20T18:02:11.000Z", "test": false,
"data": { "eventId": "3f0b…", "orderId": "c41d…", "tickets": [
{ "id": "t1…", "priceId": "p1…", "priceName": "General", "holderName": "Ana Pérez", "checkedInAt": null, "gate": null, "transferredAt": null, "voidedAt": null, "createdAt": "2026-11-20T18:02:11.000Z" },
{ "id": "t2…", "priceId": "p1…", "priceName": "General", "holderName": "Ana Pérez", "checkedInAt": null, "gate": null, "transferredAt": null, "voidedAt": null, "createdAt": "2026-11-20T18:02:11.000Z" }
] }
}ticket.refunded
{
"id": "a7c0…", "type": "ticket.refunded", "createdAt": "2026-11-22T09:15:00.000Z", "test": false,
"data": { "eventId": "3f0b…", "orderId": "c41d…", "tickets": [
{ "id": "t1…", "priceId": "p1…", "priceName": "General", "holderName": "Ana Pérez", "checkedInAt": null, "gate": null, "transferredAt": null, "voidedAt": "2026-11-22T09:15:00.000Z", "createdAt": "2026-11-20T18:02:11.000Z" }
] }
}ticket.transferred
{
"id": "d3f9…", "type": "ticket.transferred", "createdAt": "2026-11-25T12:00:00.000Z", "test": false,
"data": { "eventId": "3f0b…", "orderId": "c41d…", "tickets": [
{ "id": "t2…", "priceId": "p1…", "priceName": "General", "holderName": "Luis Gómez", "checkedInAt": null, "gate": null, "transferredAt": "2026-11-25T12:00:00.000Z", "voidedAt": null, "createdAt": "2026-11-20T18:02:11.000Z" }
] }
}ticket.checked_in
{
"id": "e8a1…", "type": "ticket.checked_in", "createdAt": "2026-12-05T21:04:11.000Z", "test": false,
"data": { "eventId": "3f0b…", "orderId": "c41d…", "tickets": [
{ "id": "t1…", "priceId": "p1…", "priceName": "General", "holderName": "Ana Pérez", "checkedInAt": "2026-12-05T21:04:10.000Z", "gate": "Puerta 1", "transferredAt": null, "voidedAt": null, "createdAt": "2026-11-20T18:02:11.000Z" }
] }
}ping
{ "id": "f0e2…", "type": "ping", "createdAt": "2026-11-14T10:00:00.000Z", "test": true, "data": { "message": "Prueba de webhook de Remolom", "webhookId": "5b7a…" } }Verificar la firma
v1 = hex(hmac_sha256(secreto, t + "." + cuerpo_crudo)).
- Calcula la firma sobre el cuerpo tal cual llega, antes de parsear el JSON.
- Compárala en tiempo constante.
- Rechaza la petición si
ttiene más de 5 minutos (evita reenvíos).
Node
import { createHmac, timingSafeEqual } from 'node:crypto'
export function verify(secret, rawBody, header) {
const { t, v1 } = Object.fromEntries(header.split(',').map((p) => p.split('=')))
const expected = createHmac('sha256', secret).update(`${t}.${rawBody}`).digest('hex')
const ok = v1?.length === expected.length && timingSafeEqual(Buffer.from(v1), Buffer.from(expected))
return ok && Math.abs(Date.now() / 1000 - Number(t)) < 300
}
// Express: el cuerpo crudo, sin express.json() en esta ruta.
app.post('/webhooks/remolom', express.raw({ type: 'application/json' }), (req, res) => {
if (!verify(process.env.REMOLOM_WEBHOOK_SECRET, req.body.toString('utf8'), req.get('Remolom-Signature') ?? '')) return res.sendStatus(400)
const evt = JSON.parse(req.body)
// deduplica por evt.id y responde rápido; el trabajo pesado, en segundo plano
res.sendStatus(200)
})Python
import hashlib, hmac, os, time
from flask import Flask, request
app = Flask(__name__)
def verify(secret: str, raw_body: bytes, header: str) -> bool:
parts = dict(p.split("=", 1) for p in header.split(","))
expected = hmac.new(secret.encode(), f"{parts['t']}.".encode() + raw_body, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, parts.get("v1", "")) and abs(time.time() - int(parts["t"])) < 300
# Flask
@app.post("/webhooks/remolom")
def remolom():
if not verify(os.environ["REMOLOM_WEBHOOK_SECRET"], request.get_data(), request.headers.get("Remolom-Signature", "")):
return "", 400
evt = request.get_json()
return "", 200PHP
function verify(string $secret, string $rawBody, string $header): bool {
parse_str(str_replace(',', '&', $header), $p);
$expected = hash_hmac('sha256', $p['t'] . '.' . $rawBody, $secret);
return hash_equals($expected, $p['v1'] ?? '') && abs(time() - (int) $p['t']) < 300;
}
$raw = file_get_contents('php://input');
if (!verify(getenv('REMOLOM_WEBHOOK_SECRET'), $raw, $_SERVER['HTTP_REMOLOM_SIGNATURE'] ?? '')) {
http_response_code(400);
exit;
}
$evt = json_decode($raw, true);
http_response_code(200);Reintentos
- Cuenta como entregado un 2xx en menos de 10 segundos. Las redirecciones no se siguen: cuentan como fallo.
- Si falla, se reintenta a los 1 min, 5 min, 30 min, 2 h, 6 h y 12 h (unas 21 h en total). Después la entrega queda como fallida.
- Si un endpoint lleva 3 días seguidos fallando se desactiva y avisamos a los owners y admins de la empresa. Una entrega correcta reinicia la cuenta. Reactívalo desde el panel o con
PATCH { "active": true }. - El orden no está garantizado: usa
createdAty el estado del propio objeto. - Responde rápido y procesa en segundo plano.
Probar
- Botón Enviar prueba en el panel, o
POST /v1/webhooks/:id/test: manda unpingal momento, sin reintentos, y te devuelve{ ok, code, error }. - Para probar el flujo completo, crea un webhook en modo Prueba y usa una clave
rk_test_: cada evento que crees disparaevent.createdcon"test": true. - En el panel ves las últimas entregas de cada webhook con su código de respuesta.