Recopilar
Para qué se usan los webhooks
Un webhook es una URL que das a otra persona. Cuando ocurre algo en su lado, hace POST de JSON a esa URL. El polling es lo contrario: sigues preguntando a una API si cambió algo. Esta página usa las dos ideas sobre los eventos de este sitio. El laboratorio de API muestra una petición que tú empiezas, y el laboratorio de llamadas edita un script que hace una.
Entender el laboratorioCómo usarlo y por qué querrías hacerlo
Por qué querrías hacerlo
Un cuerpo JSON se firma, se comprueban el HMAC y una marca de tiempo de cinco minutos, y un primer fallo forzado se reintenta una vez con el mismo id de entrega. Después de Aceptar un envío encola el nombre del evento, no la URL.
Cómo usarlo
- Enviar firma el cuerpo en bruto.
- Una marca de tiempo vieja o una firma mala se rechazan.
- El primer fallo integrado se reintenta una vez, con el mismo id de entrega.
- Después de Aceptar, webhook_lab_view lleva el nombre del evento, no la URL.
Qué es un webhook
El polling es un temporizador. Cada minuto haces GET /orders?since=… y casi cada respuesta es «nada nuevo». Un webhook invierte eso. El sistema de pedidos ya sabe que un pedido se cerró, así que te llama una vez.
El contrato es pequeño. Publicas una URL https. Ellos hacen POST de un cuerpo JSON. Respondes 2xx rápido si lo aceptas. Si agotas el tiempo o respondes 5xx, lo intentan otra vez. Tratas un delivery id repetido como el mismo evento.
El laboratorio de Llamadas eres tú preguntando a este sitio. El laboratorio de API es la misma dirección, a través del servidor. Un webhook es la otra dirección.
1
Ocurre algo
Una vista de página, un cambio de consentimiento o una puntuación que pasa de 40.
2
El emisor hace POST
El JSON va a la URL que registraste. Tú no sigues preguntando.
3
Respondes 2xx
Un éxito rápido. El trabajo lento espera en una cola.
4
O el emisor reintenta
Un timeout o un 5xx. El mismo delivery id, en un intento posterior.
La barra es una entrega que va del evento a un 2xx almacenado. Si tu endpoint falla, la misma entrega vuelve por esa línea.
Anatomía de la petición
Los proveedores nombran las cabeceras de otra forma. El trabajo es el mismo.
- Método y URL. POST, a la URL exacta que registraste. Un GET no es una entrega.
- Content-Type. Casi siempre application/json. Lee los bytes antes de decidir que son JSON.
- Firma. HMAC del raw body con un secreto compartido. Este laboratorio usa X-BBP-Signature: t=<unix>,v1=<hex> sobre la cadena timestamp.body.
- Tipo de evento. X-BBP-Event, y otra vez dentro del JSON, para que una cola pueda enrutar sin abrir el cuerpo.
- Delivery id. X-BBP-Delivery. Los reintentos lo reutilizan. Tu almacén también debería.
- Timestamp. X-BBP-Timestamp, segundos unix. Recházalo cuando se desvía más de cinco minutos, para que una petición capturada no se pueda reenviar la semana que viene.
- Cuerpo JSON. Un id, un tipo, una hora de creación y un objeto data. Sin cookies, sin correo de cuenta, sin visitor id.
Cómo etiquetan otros sistemas la misma idea
Estos fragmentos ilustran patrones de documentación pública. Este sitio no llama a Stripe, GitHub, Shopify, Slack ni Segment, y estos no son payloads en vivo de esas empresas.
Stripe
Ilustrativo. La documentación pública de Stripe firma t.rawBody con HMAC-SHA256 y envía Stripe-Signature.
POST /webhooks
Content-Type: application/json
Stripe-Signature: t=1492774577,v1=5257a869…
{"id":"evt_1","type":"checkout.session.completed","data":{"object":{"id":"cs_test"}}}GitHub
Ilustrativo. La documentación pública de GitHub pone el nombre del evento y un delivery id en las cabeceras, y el HMAC-SHA256 del raw body en X-Hub-Signature-256.
POST /hooks/github
Content-Type: application/json
X-GitHub-Event: push
X-GitHub-Delivery: 5c0e1b3a-2f4d-4c8a-9b1e-0a6d7e8f9c10
X-Hub-Signature-256: sha256=abcdef…
User-Agent: GitHub-Hookshot/1
{"ref":"refs/heads/main","repository":{"full_name":"example/app"}}Shopify
Ilustrativo. La documentación pública de Shopify envía el topic, un webhook id y un HMAC-SHA256 en base64 del raw body.
POST /webhooks/shopify
Content-Type: application/json
X-Shopify-Topic: orders/create
X-Shopify-Webhook-Id: b1c2d3e4-0000-4000-8000-000000000001
X-Shopify-Hmac-Sha256: aG1hYy1iYXNlNjQ=
{"id":820982911946154508,"financial_status":"paid"}Slack
Ilustrativo. La documentación pública de Slack firma v0:timestamp:rawBody y envía X-Slack-Signature más un timestamp que rechazas cuando es antiguo.
POST /slack/events
Content-Type: application/json
X-Slack-Request-Timestamp: 1531420618
X-Slack-Signature: v0=a2114d57b48eac39b9ad189dd8316235a7bdc556d01a…
{"type":"event_callback","event":{"type":"app_mention"}}Segment
Ilustrativo. Un webhook clásico de Segment es un payload track enviado por POST a tu URL. El secreto compartido es un HMAC del raw body, a menudo en X-Signature. Comprueba el destino que usas de verdad.
POST /segment
Content-Type: application/json
X-Signature: 3f4c9a…
{"type":"track","event":"Order Completed","userId":"anon-1","properties":{"revenue":19}}Inspector
Los botones de abajo son el emisor. POST /api/lab/webhooks/deliver firma el cuerpo con el secreto del laboratorio y lo entrega a /api/lab/webhooks/receive. El registro guarda las últimas 25 entregas de este navegador durante 24 horas. Aplica drizzle/0011_webhook_delivery.sql en Postgres antes de que esas filas persistan. Hasta entonces, el intento de la petición que acabas de hacer sigue apareciendo bajo Esta petición.
Dispara un evento
Cada botón construye un payload con los controles y pide a este sitio que lo firme y haga POST al receptor integrado. Restablecer mis datos no limpia este navegador. Solo envía el evento que emitiría un restablecimiento, con applied: false.
El banner es no es Aceptar. Ponlo en el payload si quieres que el evento coincida. La demo sigue enviando cuando Aceptar está apagado. No carga una etiqueta de terceros.
Déjalo vacío para usar solo el receptor integrado. Una URL pegada tiene que ser https en un host público. Se rechazan localhost, las direcciones privadas, las redirecciones y este sitio. El servidor comprueba la dirección antes de conectar, corta a los 2,5 segundos y no guarda el cuerpo de la respuesta.
Cuerpo exacto
Antes de un envío, este es el bloque de datos de una vista de página con los controles de arriba. Después de un envío, el panel es el JSON en bruto que se firmó, más la cabecera de la firma.
{
"type": "page_view",
"data": {
"path": "/es/lab/webhooks",
"consent": "unknown",
"title": "Webhooks"
}
}Registro de entregas
Las últimas entregas del id anónimo de este navegador. Las filas caducan a las 24 horas. El registro se actualiza solo.
Leyendo el registro de entregas de este navegador.
Seguridad
El secreto del laboratorio es bbp-lab-webhook-secret. Está publicado en esta página a propósito. Solo firma estas entregas de demo. No lo reutilices en un endpoint real.
Un receptor real guarda el secreto en el entorno, no en la página. Compara el HMAC calculado con la cabecera usando una comparación de tiempo constante, para que el tiempo que tardas en comprobar no diga a un atacante qué carácter falló. Rechaza un timestamp fuera de una ventana corta, cinco minutos en este laboratorio, para que una petición copiada no se pueda reenviar después. Guarda el delivery id y, cuando lo veas otra vez después de un 2xx, devuelve 2xx y no repitas el efecto secundario.
Sirve la URL solo por https. Una lista de IPs permitidas es un segundo cierre para los proveedores que publican sus rangos de salida. No sustituye a la firma, porque esos rangos cambian y un proxy compartido puede estar dentro. Rota el secreto aceptando el valor nuevo y el anterior durante un día, y luego borra el anterior.
La URL opcional de esta página es la dirección peligrosa: tu servidor llamaría a una dirección que escribió un visitante. La ruta solo permite https, rechaza localhost, link-local y los rangos privados, rechaza los hosts de este sitio, resuelve el DNS y conecta solo a esas direcciones públicas, no sigue redirecciones, corta a los 2,5 segundos y descarta el cuerpo de la respuesta. No se guardan las query strings. Diez envíos por minuto y navegador.
Verifica esta firma
El emisor firmó los bytes originales con el secreto del laboratorio y el timestamp fijo 1760000000. Cambia el payload o el secreto y comprueba. La comparación es contra esa firma original, no contra una nueva del texto editado.
Aún no hay comprobación.
Fiabilidad
Responde 2xx en cuanto la firma cuadre y el cuerpo esté guardado. Haz la escritura en el CRM, la inserción en el almacén o la publicación en Slack en una cola. Si haces ese trabajo dentro de la petición, salta el tiempo de espera del emisor y recibes el mismo evento otra vez mientras el primero sigue en marcha.
Los reintentos usan backoff exponencial: unos segundos, luego un minuto, luego más, con un tope. Este inspector comprime eso. Si falla el primer intento, el segundo es 400 milisegundos después, con el mismo delivery id. Un emisor de producción esperaría más, y al final desistiría.
El montón de lo abandonado es un dead letter. Algo que una persona puede reenviar después de corregir el fallo. El orden no forma parte del contrato. Un evento posterior puede llegar antes que uno anterior, y el mismo evento puede llegar dos veces. Tu manejador se apoya en el delivery id, no en «este es el siguiente».
Avisa por la tasa de respuestas que no son 2xx, por la edad de la entrega sin confirmar más antigua y por una parada repentina. Un endpoint en silencio es peor que un 500 ruidoso, porque el emisor puede estar reintentando hacia un agujero que no estás mirando.
Un receptor
Cada muestra lee el raw body, comprueba el timestamp y el HMAC, y solo entonces parsea el JSON. Sustituye el secreto. El curl usa el secreto publicado del laboratorio contra la ruta receive de este sitio.
Route handler de Next.js
request.text() es el raw body. request.json() lo consumiría antes, y un stringify posterior no coincidiría con la firma.
import { createHmac, timingSafeEqual } from "node:crypto"
import { NextResponse, type NextRequest } from "next/server"
export const dynamic = "force-dynamic"
const SECRET = process.env.WEBHOOK_SECRET ?? ""
export async function POST(request: NextRequest) {
const raw = await request.text()
const timestamp = request.headers.get("x-bbp-timestamp") ?? ""
const header = request.headers.get("x-bbp-signature") ?? ""
if (!verify(raw, timestamp, header, SECRET)) {
return NextResponse.json({ error: "signature" }, { status: 401 })
}
const event = JSON.parse(raw) as { id?: string }
// Enqueue event.id. Do the slow work after this response.
return NextResponse.json({ received: true })
}
function verify(raw: string, timestamp: string, header: string, secret: string) {
const age = Math.abs(Date.now() / 1000 - Number(timestamp))
if (!secret || !Number.isFinite(age) || age > 300) return false
const expected = createHmac("sha256", secret).update(timestamp + "." + raw).digest("hex")
const given = header.split(",").map((part) => part.trim()).find((part) => part.startsWith("v1="))?.slice(3) ?? ""
const left = Buffer.from(expected)
const right = Buffer.from(given)
return left.length === right.length && timingSafeEqual(left, right)
}
Python (FastAPI)
request.body() son los bytes en bruto. hmac.compare_digest es la comparación de tiempo constante.
import hashlib, hmac, time
from fastapi import FastAPI, HTTPException, Request
app = FastAPI()
SECRET = b"replace-with-your-secret"
@app.post("/webhooks/bbp")
async def receive(request: Request):
raw = await request.body()
timestamp = request.headers.get("x-bbp-timestamp", "")
header = request.headers.get("x-bbp-signature", "")
if not verify(raw, timestamp, header):
raise HTTPException(status_code=401, detail="signature")
# Queue the raw body. Return before the slow work.
return {"received": True}
def verify(raw: bytes, timestamp: str, header: str) -> bool:
try:
age = abs(time.time() - int(timestamp))
except ValueError:
return False
if age > 300:
return False
expected = hmac.new(SECRET, f"{timestamp}.".encode() + raw, hashlib.sha256).hexdigest()
given = ""
for part in header.split(","):
part = part.strip()
if part.startswith("v1="):
given = part[3:]
return hmac.compare_digest(expected, given)
curl
Simula un emisor. El delivery id es del_lab_demo. Envíalo dos veces y la segunda fila es un duplicado.
BODY='{"id":"evt_lab_demo","type":"page_view","created":0,"data":{"path":"/lab/webhooks","consent":"unknown"}}'
TS=$(date +%s)
SIG=$(printf '%s' "${TS}.${BODY}" | openssl dgst -sha256 -hmac 'bbp-lab-webhook-secret' | awk '{print $2}')
curl -sS -D - -o /tmp/webhook-body.txt -X POST 'https://www.blackboxpersonalization.com/api/lab/webhooks/receive' \
-H 'content-type: application/json' \
-H "x-bbp-timestamp: ${TS}" \
-H "x-bbp-signature: t=${TS},v1=${SIG}" \
-H 'x-bbp-event: page_view' \
-H 'x-bbp-delivery: del_lab_demo' \
--data-binary "${BODY}"
Dónde lo usa de verdad la analítica
Conversiones offline y el laboratorio de lado servidor llaman al Measurement Protocol de Google. Eso es una API: haces POST a Google. No es un webhook. Úsalo cuando un acuerdo se cierra en un sistema que Google no puede ver, y aún tienes el client id.
Un webhook encaja cuando el otro sistema es el que se entera del hecho. Un CRM como Salesforce o HubSpot puede hacer POST de un lead o de un cambio de etapa a tu URL. Un cambio de consentimiento en este sitio puede hacer POST a un servidor de etiquetas o a un CRM para que dejen de usar un id que acabas de soltar. Una puntuación de intención alta puede hacer POST a Slack. Zapier y Make son enrutadores de webhooks: reciben el POST y luego llaman a la API siguiente.
Un CDP que reenvía un evento tiene la misma forma. El CDP es el emisor. Tu almacén, tu plataforma de anuncios o tu herramienta de soporte es el receptor. Prefiere un webhook cuando el emisor conoce el momento y puede reintentar. Prefiere una API cuando eres tú quien lo sabe, o cuando tienes que traer un informe. Prefiere un stream cuando necesitas un registro retenido y ordenado que muchos consumidores leen a su ritmo. Un webhook es una notificación. No es una base de datos.
Consentimiento en este sitio se queda en el navegador hasta Aceptar. El inspector sigue enviando cuando haces clic, porque se lo pediste. Con Aceptar activado, el clic también registra webhook_lab_view con el nombre del evento y si se puso una URL personalizada. La URL en sí no está en ese hit.
Pruebas y el raw body
webhook.site y los buzones de peticiones parecidos te dan una URL https y muestran el POST. Pega esa URL en el inspector si quieres ver llegar el cuerpo firmado fuera de este sitio. ngrok y otros túneles hacen lo mismo para un servidor en tu máquina. El inspector de esta página es la misma idea con el receptor ya en marcha aquí.
Reenvía volviendo a enviar. Un clic nuevo acuña un delivery id nuevo. La muestra de curl reutiliza del_lab_demo, que es como ves el camino del duplicado. Registra el delivery id, el estado que devolviste y la latencia. No registres el secreto ni una query string de la URL de otra persona.
Los fallos habituales son un tiempo agotado, porque el manejador hizo el trabajo antes de responder, un 401, porque el secreto, el timestamp o los bytes difieren, y un error de parseo que ocurre antes de la verificación. En una ruta de Next.js, llama a await request.text() y verifica esos caracteres. request.json() lee el stream, así que después no puedes obtener los bytes originales. Aunque pudieras, JSON.stringify del valor parseado puede reordenar claves o cambiar los espacios. Un proxy que añade un salto de línea también cambia el HMAC. Firma y verifica un único buffer canónico, y guarda ese buffer para volver a encolar.
Práctica
- En el inspector, deja «Falla el primer intento integrado» activado. Pon la puntuación de intención en 40 o más y envía Umbral de intención. Esta petición debería mostrar el intento 1 como HTTP 500 y el intento 2 como HTTP 200, con un delivery id.
- En Verifica esta firma, añade un espacio al raw body y comprueba. Debería fallar. Vuelve a poner el cuerpo original. Debería pasar. Cambia un carácter del secreto. Debería fallar otra vez.
- Envía el mismo curl dos veces. El segundo resultado guardado debería ser Duplicado, omitido, y nada del payload debería haberse ejecutado dos veces. En este laboratorio el payload no ejecuta un efecto secundario en ningún caso. La fila es la prueba.
- Responde a las preguntas. Usan solo las reglas de arriba.
Glosario
- Webhook
- Una URL https que recibe un POST cuando otro sistema tiene un evento.
- Polling
- Preguntar a una API con un temporizador si hay algo nuevo.
- Payload
- El cuerpo de ese POST. Aquí es JSON.
- HMAC
- Un hash del cuerpo mezclado con un secreto compartido. Este laboratorio usa SHA-256.
- Replay
- Enviar otra vez una petición capturada. Una ventana corta de timestamp deja inútil una captura antigua.
- Idempotencia
- Hacer el efecto secundario una vez aunque la entrega llegue dos veces. El delivery id es la clave.
- Backoff
- Esperar más entre reintentos para no machacar un receptor roto.
- Dead letter
- Una entrega que el emisor dejó de reintentar. Una persona, o un trabajo posterior, puede reenviarla.
- Raw body
- Los bytes exactos que firmó el emisor, antes de parsear el JSON.
- SSRF
- Engañar a un servidor para que llame a una dirección a la que no debería, como localhost o una IP de metadatos en la nube. La URL opcional de esta página se comprueba para rechazarlas.
RecorridoCómo lo hicimosMostrarOcultar
El ajuste de proveedor de ejemplo está marcado abajo. Los números de eVar y de event son ejemplos. Este laboratorio no llama a Adobe.
El laboratorio de webhooks firma un cuerpo JSON, comprueba el HMAC y un timestamp de cinco minutos, y reintenta una vez un primer fallo forzado con el mismo delivery id. Después de Aceptar, un envío encola webhook_lab_view, y el laboratorio no llama a Adobe.
Firmar el raw body
signWebhook es el HMAC-SHA256 del timestamp, un punto y el raw body. La cabecera es t igual al timestamp y v1 igual al hex.
Rechazar una firma vieja o que no coincide
verifyWebhook exige un timestamp de 10 dígitos dentro de la ventana de tolerancia, un hex de 64 caracteres y una comparación de tiempo constante. Una longitud distinta devuelve false antes de la comparación.
Reintentar el primer fallo integrado
failFirst hace dos intentos. El primero llama al receptor integrado con forceFail, que guarda el resultado retry y el estado 500. Un estado de 200 a 299 detiene el bucle. Si no, espera 400 milisegundos y reutiliza el delivery id.
Encolar el nombre del evento, no la URL
Después de Aceptar, webhook_lab_view envía webhook_event, destination custom o builtin, y attempt_count. La cadena de destino en sí no es un parámetro.
Del código
La ventana del timestamp y una comparación de tiempo constante del HMAC.
export function verifyWebhook(
rawBody: string,
timestamp: string,
header: string,
secret: string,
nowSec = Date.now() / 1000,
) {
if (!secret || !/^\d{10}$/.test(timestamp)) return false
const issued = Number(timestamp)
if (!Number.isFinite(issued) || Math.abs(nowSec - issued) > SIGNATURE_TOLERANCE_SEC) return false
const given = providedHex(header)
if (!/^[0-9a-f]{64}$/.test(given)) return false
const expected = signWebhook(rawBody, timestamp, secret)
const left = Buffer.from(expected, "utf8")
const right = Buffer.from(given, "utf8")
if (left.length !== right.length) return false
return timingSafeEqual(left, right)
}El primer intento puede forzarse a fallar. Un 2xx detiene el bucle. Si no, espera 400 milisegundos.
attempt,
forceFail: input.failFirst && attempt === 1,
})
if (result.state !== "ok") state = result.state
attempts.push(
view({
attempt,
destination: BUILTIN,
status: result.status,
latencyMs: result.latencyMs,
outcome: result.outcome,
deliveryId,
event: input.event,
payload: raw,
}),
)
if (result.status >= 200 && result.status < 300) break
if (attempt < tries) await sleep(400)Google y Adobe
Google encola webhook_lab_view después de Aceptar. Adobe es un ejemplo de los mismos campos.
Después de Aceptar, un envío encola webhook_lab_view con webhook_event, destination custom o builtin, y attempt_count. La URL de destino no es un parámetro. Esto se encola solo después de Aceptar. Este sitio no llama a Adobe.
Forma simplificada del objeto encolado después de Aceptar. Registra cualquier parámetro nuevo como dimensión personalizada con alcance de evento. Este sitio no llama a gtag('set').
dataLayer.push({
event: "webhook_lab_view",
webhook_event: "intent_threshold",
destination: "builtin",
attempt_count: 2,
})Implementación de ejemplo. Este sitio no llama a Adobe. eVar116, prop116 y event116 son números de variable de ejemplo. En Launch, un elemento de datos lee el valor y una regla lo envía cuando el valor cambia. En el report suite, habilita eVar116 con asignación Most Recent y haz que expire en el hit. Una processing rule no hace falta si el elemento de datos se mapea directo a esa eVar.
Payload de alloy de ejemplo. _example es un esquema de relleno, no un inquilino real.
alloy("sendEvent", {
xdm: {
eventType: "web.webinteraction.linkClicks",
_example: {
webhookEvent: "intent_threshold",
},
},
})Hit de ejemplo. eVar116 tiene alcance de hit en este ejemplo. prop116 muere en el mismo hit.
s.eVar116 = "intent_threshold"
s.prop116 = "intent_threshold"
s.events = "event116"
s.linkTrackVars = "eVar116,prop116,events"
s.linkTrackEvents = "event116"
s.tl(true, "o", "webhook_lab_view")Traducción
Cada campo del laboratorio, el nombre en GA4 y la variable de Adobe de ejemplo. El alcance es la parte que suele perderse en la traducción.
Evento del webhook
GA4. Parámetro webhook_event en webhook_lab_view. Los valores incluyen page_view, segment_change e intent_threshold.
Adobe. eVar116 de ejemplo, expira en el hit.
Alcance. Evento. Una propiedad de usuario conservaría el último evento de demo durante la visita.
Tipo de destino
GA4. Parámetro destination. Los valores son builtin o custom. La URL no se envía.
Adobe. prop116 de ejemplo, que muere en el hit.
Alcance. Evento en el hit. No es una propiedad de usuario.
Conteo de intentos
GA4. Parámetro attempt_count en webhook_lab_view.
Adobe. eVar116 de ejemplo para el conteo. No es un reintento guardado en el usuario.
Alcance. Evento. Describe este envío, no la visita.
Delivery id
GA4. No es un parámetro. El receptor lo usa para tratar una repetición como un duplicado.
Adobe. prop116 de ejemplo. No se envía.
Alcance. Una clave de idempotencia en el servidor. No es un parámetro de hit ni una propiedad de usuario.
Recomendado a continuación
Por qué estas propuestasLeyendo las transiciones de recorrido…