Webhooks

Receive HMAC-signed delivery events; manage endpoints and deliveries (`publiq.webhooks`).

The webhooks resource covers an endpoint lifecycle: create (receiving the signing secret), list, test, rotate the secret, delete and inspect deliveries — including HTTP attempts and replay.

Method reference

`webhooks.create`

webhooks.create(params) → Promise<Webhook>

Registers a new webhook endpoint: a destination URL and the event types it should receive (e.g. delivery, bounce, open).

Parameters

Parameter	Type	Description
`url`Required	`string`	Destination URL. Must be https.
`eventTypes`Required	`string[]`	Non-empty list of event types (e.g. `['message.delivered', 'message.bounced', 'message.opened']`).

Returns: The created webhook — the response includes the secret (shown only here; store it to verify signatures).

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

Always verify the HMAC signature (Publiq-Signature header) using the secret before trusting a received payload. See Observability. The secret is only returned on create and rotate — lost it? Use rotateSecret.

`webhooks.list`

webhooks.list() → Promise<WebhookList>

List the webhook endpoints registered on the organization.

Returns: List envelope { object: "list", data: Webhook[] }. Secrets are not included.

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

`webhooks.delete`

webhooks.delete(id) → Promise<void>

Removes a webhook endpoint. No new events will be sent to it.

Parameters

Parameter	Type	Description
`id`Required	`string`	ID of the webhook to remove.

Returns: Nothing (204 No Content).

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

`webhooks.rotateSecret`

webhooks.rotateSecret(id) → Promise<Webhook>

Generates a new signing secret for the endpoint, invalidating the previous one. Use it when you suspect a leak or as a security routine.

Parameters

Parameter	Type	Description
`id`Required	`string`	Webhook ID.

Returns: The webhook with the new secret — the previous one stops validating signatures immediately.

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>

Sends a sample event to the endpoint so you can verify receiving and signature validation are wired up correctly.

Parameters

Parameter	Type	Description
`id`Required	`string`	ID of the webhook to test.

Returns: The resulting WebhookDelivery from the test event.

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

`webhooks.deliveries`

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

List an endpoint deliveries — each one an event dispatched to the configured URL — newest first, cursor-paginated.

Parameters

Parameter	Type	Description
`id`Required	`string`	Webhook ID.
`limit`Optional	`number`	Items per page (default 20, max 100).
`after`Optional	`string`	Cursor: `id` of the last item on the previous page.

Returns: List envelope { object: "list", data: WebhookDelivery[] }, cursor-paginated.

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 });

Your debugging tool: inspect deliveries to see which events were dispatched and each one status. Combine with deliveryAttempts to see each HTTP attempt details.

`webhooks.deliveryAttempts`

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

List the HTTP attempts of a specific delivery — status codes, latency and retries.

Parameters

Parameter	Type	Description
`deliveryId`Required	`string`	Delivery ID.

Returns: The list of HTTP attempts made for that delivery, oldest to newest.

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

Your debugging tool: inspect attempts to understand why an endpoint failed (timeout, 4xx, 5xx), then use replayDelivery once fixed.

`webhooks.replayDelivery`

webhooks.replayDelivery(deliveryId) → Promise<WebhookDelivery>

Re-sends a past delivery — useful after fixing your endpoint, to confirm it now processes the event correctly.

Parameters

Parameter	Type	Description
`deliveryId`Required	`string`	ID of the delivery to replay.

Returns: The new WebhookDelivery generated by the replay.

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

Your debugging tool: use it after fixing the endpoint (see deliveryAttempts) to reprocess an event without waiting for a new real trigger.

Examples show Node, Python and PHP. In Python methods are snake_case (e.g. cancel_run, from_spec) and take a dict; in PHP they are camelCase and take an associative array. Body keys are always camelCase (templateKey, firstName, scheduledAt) — API responses come back in snake_case.