Ganchos web
Preparar su producto para eventos de webhook.
Cree y administre puntos finales de webhook del cliente para uso, facturación y API eventos clave del ciclo de vida, luego preparar a los receptores para la entrega firmada, los reintentos y la observabilidad redactada.
Última actualización: July 12, 2026. Examples uso safe placeholders y hacer no incluir real secretos, clave APIs, o customer cargas útiles.
regla del receptor
Prepare a los receptores para verificar primero la firma de la carga útil sin procesar, registre cada ID de evento una vez y devuelva 2xx solo después de que su aplicación pueda procesar o ignorar el evento de manera segura.
Ruta de instalación
Cinco pasos desde el punto final URL hasta la preparación para la entrega.
Step 1
Crear un punto final receptor
Exponga un HTTPS URL que acepte solicitudes POST y pueda leer el cuerpo de la solicitud sin formato antes del análisis JSON.
Step 2
Seleccionar eventos
Elija los tipos de eventos de ciclo de vida clave de uso, suscripción, factura o API para los que su receptor debería estar preparado.
Step 3
Guarde el secreto de firma
Copie el secreto del punto final una vez y guárdelo en un administrador de secretos para que los receptores estén listos para la entrega del webhook firmado.
Step 4
Manejo de reintentos del plan
Diseñe receptores idempotentes para que los intentos repetidos de entrega sean seguros cuando el envío de webhooks esté habilitado.
Step 5
Observabilidad del plan
Realice un seguimiento del estado del punto final ahora y defina los registros de entrega que su equipo necesitará para el envío de webhooks en el futuro.
Punto final URL
Registre un punto final por entorno.
Utilice URL independientes para el desarrollo, la puesta en escena y la producción, de modo que las entregas de pruebas futuras nunca provoquen efectos secundarios de producción.
{
"name": "Production usage events",
"url": "https://example.com/api/unlimitedcodex/webhook",
"events": [
"usage.threshold_reached",
"subscription.updated",
"invoice.payment_failed"
]
}Selección de eventos
Seleccione los tipos de eventos para los que su receptor debería estar preparado.
Mantenga cada receptor estrecho mientras se prepara la entrega. Es posible que un servicio de facturación solo necesite eventos de facturación, mientras que una barrera de uso solo necesite elementos fijos de eventos de umbral.
| Evento | Contexto desencadenante | Caso de uso del receptor |
|---|---|---|
| uso.umbral_alcanzado | Un espacio de trabajo cruza un umbral de uso configurado. | Prepare mensajes para los propietarios de cuentas, suspenda trabajos costosos o solicite a los propietarios de facturas que revisen la adecuación del paquete. |
| suscripción.actualizada | El estado de la suscripción, el paquete o el período de facturación cambian. | Actualizar los derechos locales y los detalles de acceso. |
| api_key.revocada | Se revoca una clave API. | Invalide las credenciales almacenadas en caché y prepare una notificación al equipo propietario. |
| factura.pagada | Una factura está marcada como pagada. | Desbloquee el acceso pago, concilie el estado de facturación o actualice los registros de la cuenta. |
| factura.pago_fallido | Falla el pago de una factura. | Prepare un flujo de reclamación, mensajes para el propietario de la cuenta o límites para el uso riesgoso en segundo plano. |
Secreto de firma
Verifique el cuerpo crudo antes de procesarlo.
Los secretos de firma de webhooks se muestran una vez. Almacene el secreto en una variable de entorno o administrador de secretos, luego utilícelo para validar las firmas con marca de tiempo HMAC SHA-256 cuando el envío de webhook esté habilitado.
signature value usa t=timestamp,v1=signature. Esto example names header x-ucx-signature; uso signature header shown para tu entrega.
import { createHmac, timingSafeEqual } from "crypto";
function verifySignature(rawBody, signatureHeader, secret) {
const parts = Object.fromEntries(
signatureHeader.split(",").map((part) => part.split("="))
);
const timestamp = Number(parts.t);
const signature = parts.v1;
if (!Number.isInteger(timestamp) || !signature) {
return false;
}
const signedPayload = `${timestamp}.${rawBody}`;
const expected = createHmac("sha256", secret)
.update(signedPayload)
.digest("hex");
const left = Buffer.from(expected, "hex");
const right = Buffer.from(signature, "hex");
return left.length === right.length && timingSafeEqual(left, right);
}Ejemplo de receptor
Mantenga a los manejadores pequeños e idempotentes.
Utilice este patrón de receptor una vez habilitada la entrega saliente: analice el evento después de la verificación de la firma, registre el ID del evento y luego transfiera el trabajo lento a su propia cola.
export async function POST(request) {
const rawBody = await request.text();
const signature = request.headers.get("x-ucx-signature") ?? "";
const secret = process.env.UCX_WEBHOOK_SECRET;
if (!secret || !verifySignature(rawBody, signature, secret)) {
return new Response("Invalid signature", { status: 400 });
}
const event = JSON.parse(rawBody);
// Store event.id before doing side effects so retries stay idempotent.
await recordWebhookEvent(event.id, event.type);
return Response.json({ received: true });
}Forma de carga útil segura
Las cargas útiles de eventos deben tratarse como metadatos operativos. No incluya mensajes, claves API sin procesar, datos de tarjetas de pago ni secretos de clientes en registros o dispositivos de webhook.
{
"id": "evt_example_123",
"type": "usage.threshold_reached",
"created": "2026-07-06T12:00:00.000Z",
"data": {
"workspaceId": "workspace_example",
"metric": "requests",
"thresholdPercent": 80
}
}Reintentos
Diseño para repetidos intentos de entrega.
Cuando el envío de webhook está habilitado, las fallas de red, los tiempos de espera y las respuestas que no son 2xx pueden provocar reintentos. Cree controladores que puedan recibir el mismo evento más de una vez sin duplicar efectos secundarios.
Devuelve 2xx después de un trabajo duradero
Escriba el ID del evento o ponga en cola el trabajo antes de que el resultado sea exitoso.
Utilice ID de eventos para idempotencia
Ignore los duplicados que ya hayan sido grabados o procesados.
Mantenga a los manejadores rápidos
Mueva el correo electrónico, la sincronización de facturación y los trabajos largos a una cola interna.
No dependa del pedido exacto
Utilice el estado actual de los recursos cuando sea posible en lugar de asumir que los eventos llegan en secuencia.
Observabilidad
Planifique el contexto del punto final redactado.
Planifique los registros de entrega en torno al contexto operativo redactado, como el tipo de evento, el punto final, el estado, el recuento de intentos, el estado de la respuesta, el cuerpo de la respuesta, la hora del próximo reintento y la hora de entrega.
Requiere HTTPS para las URL de los puntos finales de producción.
Verifique la firma HMAC con marca de tiempo antes de confiar en la carga útil.
Almacene los secretos de firma en un administrador secreto, no en el código fuente.
Trate a los controladores de eventos como idempotentes porque los intentos de entrega pueden repetirse.
Devuelve 2xx solo después de que el evento se registre de forma segura o se ignore intencionalmente.
No registre secretos de firma sin procesar, claves API, detalles de pago, avisos ni cargas útiles de clientes.
Pruebas locales
Pruebe con un túnel antes de la producción.
Apunte un punto final de webhook de desarrollo a un túnel temporal, preparar un dispositivo de evento seguro, verifique el asistente de firma y confirme que su controlador almacene un único registro de evento.
# Use a local tunnel URL as the endpoint while testing. https://your-tunnel.example/api/unlimitedcodex/webhook # Keep the signing secret out of source code. UCX_WEBHOOK_SECRET=whsec_ucx_placeholder_value
FAQ
Preguntas sobre la configuración del webhook.
¿A qué eventos puedo suscribirme?
La administración de puntos finales de webhook del cliente admite la selección de uso.threshold_reached, suscripción.updated, api_key.revoked, factura.pagada y factura.pago_failed para que los receptores se puedan configurar antes de habilitar el envío de webhook.
¿Cómo se firman las entregas de webhooks?
Prepare los receptores para una firma con marca de tiempo HMAC SHA-256. El valor de la firma sigue el formato t=marca de tiempo,v1=firma y los receptores deben verificarlo con el cuerpo de la solicitud sin procesar y el secreto de firma.
¿Qué suposiciones de entrega debería hacer mi manejador?
Cuando el envío de webhooks está habilitado, no asuma una entrega única, un pedido estricto o un intento final exitoso. Cree controladores idempotentes y registre los ID de eventos antes de los efectos secundarios.
¿Puedo rotar un secreto de firma de webhook?
Sí. Al rotar un punto final se crea un nuevo secreto de firma que se muestra una vez. Almacene el nuevo valor de forma segura y actualice el receptor antes de depender de él en producción.
Herramientas gratuitas
Generar iniciadores de receptores de webhooks
Controladores de scaffolding, archivos env, claves de alcance y patrones de reintento seguro antes de habilitar eventos de facturación o uso.
Generador de webhooks
Genere controladores de webhook de Node o Python con verificación de firma para eventos unlimitedcodex.
Configuración del entorno
Genere bloques.env.example a partir de puntos finales, entornos y necesidades de webhooks seleccionados.
Configurador de alcance
Seleccione cargas de trabajo y genere alcances con privilegios mínimos,.env.example y una lista de verificación de rotación.
Reintentar simulador
Ajuste la configuración de retroceso y reintento para ver resultados simulados y copie un fragmento del controlador de reintento.
¿Listo para preparar receptores de eventos?
Combine webhooks con controles de uso y facturación.
Revise el ajuste del paquete, el comportamiento del límite de velocidad y el manejo de errores antes de que los flujos de trabajo de eventos del cliente afecten los sistemas de cara al cliente.