Webhooks

​

Administre las entregas en la consola

• Endpoints: cree o edite un endpoint, guarde su secreto de firma de un solo uso, envíe una prueba de forma explícita o deshabilítelo y vuelva a habilitarlo. Es preferible deshabilitar para conservar el historial de entregas. Las apps suspendidas siguen siendo consultables y sus endpoints todavía se pueden deshabilitar.
• Deliveries: filtre las entregas ordinarias y las pruebas firmadas por endpoint, tipo de evento, resultado y rango de tiempo. Consulte el estado agregado, el número de intentos, el último estado de respuesta, el error seguro y las marcas de tiempo. Esto no es una línea de tiempo por intento. Las URL y el estado del endpoint que se muestran son la configuración actual, no copias históricas del destino.
• Events: inspeccione los metadatos de eventos de negocio que se pueden reenviar. Review event muestra una vista previa de un reintento a nivel de evento; Confirm retry intenta los destinos elegibles y omite los pares ya exitosos, los endpoints deshabilitados y los endpoints que ya no están suscritos. Si los destinos cambian, revise una vista previa nueva antes de confirmar.

​

Pruebe el flujo completo de pedidos

​

El sobre del evento

{
  "object": "event",
  "id": "evt_...",
  "type": "order.notification",
  "created": 1765432100,
  "data": { "order_id": "ord_...", "location_id": "str_..." }
}

​

Tipos de evento

​

Suscripción

curl -X POST $MAPLE_BASE/webhook_subscriptions \
  -H "Authorization: Bearer $MAPLE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "notification_url": "https://your-app.example.com/maple/webhooks",
    "event_types": ["order.notification", "order.cancelled"]
  }'

{
  "object": "webhook_subscription.created",
  "subscription": { "object": "webhook_subscription", "id": "dws_...", "environment": "test", "status": "enabled", "...": "..." },
  "signing_secret": "mwhsec_..."
}

​

Varias suscripciones

​

Verificación de la firma

• maple-webhook-id — el id del evento.
• maple-webhook-signature — t=<unix_seconds>,v1=<hex_hmac>.

{timestamp}.{subscription_id}.{notification_url}.{raw_body}

import { createHmac, timingSafeEqual } from 'node:crypto';

function verifyMapleWebhook(params: {
  signatureHeader: string; // maple-webhook-signature
  subscriptionId: string; // your subscription id (dws_…)
  notificationUrl: string; // the exact URL you registered
  rawBody: string; // the unparsed request body
  signingSecret: string; // mwhsec_…
  toleranceSeconds?: number; // default 300
}): boolean {
  const parts = Object.fromEntries(params.signatureHeader.split(',').map((p) => p.split('=')));
  const timestamp = Number(parts.t);
  const provided = parts.v1 ?? '';

  // Reject stale deliveries to prevent replay.
  const skew = Math.abs(Math.floor(Date.now() / 1000) - timestamp);
  if (!Number.isFinite(timestamp) || skew > (params.toleranceSeconds ?? 300)) return false;

  const signed = `${timestamp}.${params.subscriptionId}.${params.notificationUrl}.${params.rawBody}`;
  const expected = createHmac('sha256', params.signingSecret).update(signed).digest('hex');
  return expected.length === provided.length && timingSafeEqual(Buffer.from(expected), Buffer.from(provided));
}

​

Garantías de entrega

• Al menos una vez. El mismo evento puede llegar más de una vez. Elimine duplicados con el id del sobre y haga que su controlador sea idempotente.
• Responda rápido. Devuelva un 2xx de inmediato y realice el trabajo más lento de forma asíncrona. Cualquier respuesta que no sea 2xx (o un tiempo de espera agotado) cuenta como una entrega fallida.
• No se garantiza el orden. No suponga que los eventos llegan en el orden en que ocurrieron; concilie con el recurso del pedido cuando la secuencia importe.

​

Reintentos y deshabilitación automática

​

Registro de eventos

• GET /v1/webhook_events — sus eventos recientes, del más reciente al más antiguo (hasta 50). Útil para conciliación y depuración.
• GET /v1/webhook_events/{eventId} — un solo evento, con su payload data completo.
• POST /v1/webhook_events/{eventId}/replay — intenta la entrega a las suscripciones habilitadas que coinciden actualmente, omitiendo los pares con un éxito registrado. Reutiliza el id del evento y no fuerza la reentrega de lo ya exitoso. Los intentos concurrentes o un resultado incierto de red o de persistencia aún pueden producir duplicados; el receptor debe eliminarlos. Los intentos manuales fallidos son definitivos y no programan reintentos automáticos.

​

Prueba de su controlador

curl -X POST $MAPLE_BASE/webhook_subscriptions/{id}/test \
  -H "Authorization: Bearer $MAPLE_KEY"

{ "object": "webhook_test_result", "event_id": "evt_...", "delivered": true, "response_status": 200 }

​

Lista de verificación