Webhooks

Recibe eventos de entrega firmados con HMAC; gestiona endpoints y entregas (`publiq.webhooks`).

El recurso webhooks cubre el ciclo de vida de un endpoint: crear (recibiendo el secret de firma), listar, probar, rotar el secret, eliminar e inspeccionar entregas — incluyendo intentos HTTP y reenvío.

Referencia de métodos

`webhooks.create`

webhooks.create(params) → Promise<Webhook>

Registra un nuevo endpoint de webhook: una URL de destino y los tipos de evento que debe recibir (ej.: entrega, rebote, apertura).

Parámetros

Parámetro	Tipo	Descripción
`url`Obligatorio	`string`	URL de destino. Debe ser https.
`eventTypes`Obligatorio	`string[]`	Lista no vacía de tipos de evento (ej.: `['message.delivered', 'message.bounced', 'message.opened']`).

Devuelve: El webhook creado — la respuesta incluye el secret (mostrado solo aquí; guárdalo para verificar firmas).

const webhook = await publiq.webhooks.create({
url: 'https://app.example.com/hooks/publiq',
eventTypes: ['message.delivered', 'message.bounced', 'message.opened'],
});
console.log(webhook.secret); // store this — never shown again

Siempre verifica la firma HMAC (header Publiq-Signature) usando el secret antes de confiar en un payload recibido. Ver Observabilidad. El secret solo se devuelve al crear y al rotar — ¿lo perdiste? Usa rotateSecret.

`webhooks.list`

webhooks.list() → Promise<WebhookList>

Lista los endpoints de webhook registrados en la organización.

Devuelve: Envoltura de lista { object: "list", data: Webhook[] }. Los secrets no están incluidos.

const { data } = await publiq.webhooks.list();
for (const webhook of data) console.log(webhook.url, webhook.eventTypes);

`webhooks.delete`

webhooks.delete(id) → Promise<void>

Elimina un endpoint de webhook. No se enviarán más eventos a él.

Parámetros

Parámetro	Tipo	Descripción
`id`Obligatorio	`string`	ID del webhook a eliminar.

Devuelve: Nada (204 No Content).

await publiq.webhooks.delete('wh_123');

`webhooks.rotateSecret`

webhooks.rotateSecret(id) → Promise<Webhook>

Genera un nuevo secret de firma para el endpoint, invalidando el anterior. Úsalo cuando sospeches una filtración o como rutina de seguridad.

Parámetros

Parámetro	Tipo	Descripción
`id`Obligatorio	`string`	ID del webhook.

Devuelve: El webhook con el nuevo secret — el anterior deja de validar firmas de inmediato.

const webhook = await publiq.webhooks.rotateSecret('wh_123');
console.log(webhook.secret); // new secret — old one stops working now

`webhooks.test`

webhooks.test(id) → Promise<WebhookDelivery>

Envía un evento de ejemplo al endpoint para que verifiques que la recepción y la validación de firma funcionan.

Parámetros

Parámetro	Tipo	Descripción
`id`Obligatorio	`string`	ID del webhook a probar.

Devuelve: La entrega (WebhookDelivery) resultante del evento de prueba.

const delivery = await publiq.webhooks.test('wh_123');
console.log(delivery.status);

`webhooks.deliveries`

webhooks.deliveries(id, { limit?, after? }) → Promise<WebhookDeliveryList>

Lista las entregas de un endpoint — cada una un evento despachado a la URL configurada — del más reciente al más antiguo, paginado por cursor.

Parámetros

Parámetro	Tipo	Descripción
`id`Obligatorio	`string`	ID del webhook.
`limit`Opcional	`number`	Ítems por página (por defecto 20, máx. 100).
`after`Opcional	`string`	Cursor: `id` del último ítem de la página anterior.

Devuelve: Envoltura de lista { object: "list", data: WebhookDelivery[] }, paginada por cursor.

const { data } = await publiq.webhooks.deliveries('wh_123', { limit: 50 });
// next page:
const next = await publiq.webhooks.deliveries('wh_123', { after: data[data.length - 1].id });

Tu herramienta de debugging: inspecciona las entregas para ver qué eventos se despacharon y el estado de cada una. Combínalo con deliveryAttempts para ver el detalle de cada intento HTTP.

`webhooks.deliveryAttempts`

webhooks.deliveryAttempts(deliveryId) → Promise<WebhookDeliveryAttempt[]>

Lista los intentos HTTP de una entrega específica — códigos de estado, latencia y reintentos.

Parámetros

Parámetro	Tipo	Descripción
`deliveryId`Obligatorio	`string`	ID de la entrega.

Devuelve: La lista de intentos HTTP realizados para esa entrega, del más antiguo al más reciente.

const attempts = await publiq.webhooks.deliveryAttempts('whd_123');
for (const attempt of attempts) console.log(attempt.statusCode, attempt.attemptedAt);

Tu herramienta de debugging: inspecciona los intentos para entender por qué falló un endpoint (timeout, 4xx, 5xx) y luego usa replayDelivery una vez corregido.

`webhooks.replayDelivery`

webhooks.replayDelivery(deliveryId) → Promise<WebhookDelivery>

Reenvía una entrega pasada — útil después de corregir tu endpoint, para confirmar que ahora procesa el evento correctamente.

Parámetros

Parámetro	Tipo	Descripción
`deliveryId`Obligatorio	`string`	ID de la entrega a reenviar.

Devuelve: La nueva entrega (WebhookDelivery) generada por el reenvío.

const delivery = await publiq.webhooks.replayDelivery('whd_123');
console.log(delivery.status);

Tu herramienta de debugging: úsala después de corregir el endpoint (ver deliveryAttempts) para reprocesar un evento sin esperar un nuevo disparo real.

Los ejemplos muestran Node, Python y PHP. En Python los métodos son snake_case (ej.: cancel_run, from_spec) y reciben un dict; en PHP son camelCase y reciben un array asociativo. Las claves del cuerpo siempre son camelCase (templateKey, firstName, scheduledAt) — las respuestas de la API vienen en snake_case.