Webhooks

Receba eventos de entrega assinados com HMAC; gerencie endpoints e entregas (`publiq.webhooks`).

O recurso webhooks cobre o ciclo de vida de um endpoint: criar (recebendo o secret de assinatura), listar, testar, rotacionar o secret, remover e inspecionar entregas — incluindo tentativas HTTP e reenvio.

Referência de métodos

`webhooks.create`

webhooks.create(params) → Promise<Webhook>

Cadastra um novo endpoint de webhook: uma URL de destino e os tipos de evento que ela deve receber (ex.: entrega, bounce, abertura).

Parâmetros

Parâmetro	Tipo	Descrição
`url`Obrigatório	`string`	URL de destino. Precisa ser https.
`eventTypes`Obrigatório	`string[]`	Lista não vazia de tipos de evento (ex.: `['message.delivered', 'message.bounced', 'message.opened']`).

Retorna: O webhook criado — a resposta inclui o secret (exibido apenas aqui; guarde-o para verificar assinaturas).

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

Sempre verifique a assinatura HMAC (header Publiq-Signature) usando o secret antes de confiar em um payload recebido. Veja Observabilidade. O secret só é retornado na criação e na rotação — perdeu? Use rotateSecret.

`webhooks.list`

webhooks.list() → Promise<WebhookList>

Lista os endpoints de webhook cadastrados na organização.

Retorna: Envelope de lista { object: "list", data: Webhook[] }. Os secrets não são incluídos.

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

`webhooks.delete`

webhooks.delete(id) → Promise<void>

Remove um endpoint de webhook. Nenhum novo evento será enviado para ele.

Parâmetros

Parâmetro	Tipo	Descrição
`id`Obrigatório	`string`	ID do webhook a remover.

Retorna: Nada (204 No Content).

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

`webhooks.rotateSecret`

webhooks.rotateSecret(id) → Promise<Webhook>

Gera um novo secret de assinatura para o endpoint, invalidando o anterior. Use quando suspeitar de vazamento ou como rotina de segurança.

Parâmetros

Parâmetro	Tipo	Descrição
`id`Obrigatório	`string`	ID do webhook.

Retorna: O webhook com o novo secret — o anterior deixa de validar assinaturas imediatamente.

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>

Envia um evento de exemplo para o endpoint, para você verificar se o recebimento e a validação de assinatura estão funcionando.

Parâmetros

Parâmetro	Tipo	Descrição
`id`Obrigatório	`string`	ID do webhook a testar.

Retorna: A entrega (WebhookDelivery) resultante do evento de teste.

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

`webhooks.deliveries`

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

Lista as entregas de um endpoint — cada uma representa um evento despachado para a URL configurada — do mais recente ao mais antigo, com paginação por cursor.

Parâmetros

Parâmetro	Tipo	Descrição
`id`Obrigatório	`string`	ID do webhook.
`limit`Opcional	`number`	Itens por página (padrão 20, máx. 100).
`after`Opcional	`string`	Cursor: `id` do último item da página anterior.

Retorna: Envelope de lista { object: "list", data: WebhookDelivery[] }, paginado 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 });

Sua ferramenta de debugging: inspecione as entregas para ver quais eventos foram despachados e o status de cada uma. Combine com deliveryAttempts para ver os detalhes de cada tentativa HTTP.

`webhooks.deliveryAttempts`

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

Lista as tentativas HTTP de uma entrega específica — códigos de status, latência e retries.

Parâmetros

Parâmetro	Tipo	Descrição
`deliveryId`Obrigatório	`string`	ID da entrega.

Retorna: A lista de tentativas HTTP feitas para essa entrega, da mais antiga à mais recente.

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

Sua ferramenta de debugging: inspecione as tentativas para entender por que um endpoint falhou (timeout, 4xx, 5xx) e depois use replayDelivery após corrigir.

`webhooks.replayDelivery`

webhooks.replayDelivery(deliveryId) → Promise<WebhookDelivery>

Reenvia uma entrega passada — útil depois de corrigir o seu endpoint para confirmar que ele agora processa o evento corretamente.

Parâmetros

Parâmetro	Tipo	Descrição
`deliveryId`Obrigatório	`string`	ID da entrega a reenviar.

Retorna: A nova entrega (WebhookDelivery) gerada pelo reenvio.

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

Sua ferramenta de debugging: use depois de corrigir o endpoint (ver deliveryAttempts) para reprocessar um evento sem esperar por um novo disparo real.

Os exemplos mostram Node, Python e PHP. No Python os métodos são snake_case (ex.: cancel_run, from_spec) e recebem um dict; no PHP são camelCase e recebem um array associativo. As chaves do corpo são sempre camelCase (templateKey, firstName, scheduledAt) — o retorno da API vem em snake_case.