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:

RutaRespuesta
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/deliveriesLas 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:

CabeceraValor
Remolom-Signaturet=<unix>,v1=<hex>
Remolom-EventEl tipo, por ejemplo ticket.sold
Remolom-DeliveryId de esta entrega
User-AgentRemolom-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

TipoCuándodata
event.createdSe crea un evento (web, app, API, MCP, importador o feed){ event: EventDTO }
event.updatedCambia algún dato, se reactiva un cancelado o moderación lo vuelve a publicar{ event: EventDTO }
event.cancelledEl organizador lo cancela (también DELETE /v1/… o si desaparece de un feed){ event: EventDTO }
event.hiddenModeración de Remolom lo retira{ event: EventDTO }
ticket.soldUn pedido se paga (o se reserva gratis)TicketData con todas las entradas del pedido
ticket.refundedSe reembolsa un pedidoTicketData con las entradas anuladas
ticket.transferredEl titular transfiere una entradaTicketData con esa entrada y el nuevo holderName
ticket.checked_inSe valida en puerta (también lecturas sin conexión al sincronizar)TicketData con esa entrada
pingBotó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

json
{
  "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

json
{
  "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

json
{
  "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

json
{
  "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

json
{
  "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

json
{ "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)).

  1. Calcula la firma sobre el cuerpo tal cual llega, antes de parsear el JSON.
  2. Compárala en tiempo constante.
  3. Rechaza la petición si t tiene más de 5 minutos (evita reenvíos).

Node

js
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

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 "", 200

PHP

php
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

Probar