Peeker Partner API

Create a listener in the Partner portal, choose event types, and store the signing secret. Peeker POSTs JSON to your HTTPS URL.

Request format

Header	Use
`Peeker-Event-Id`	Stable event ID. Dedupe on this.
`Peeker-Timestamp`	Unix timestamp used in the signature
`Peeker-Signature`	`v1=<hex hmac-sha256>`

{
	"id": "evt_01HZX0EV1A2B3C4D5E6F7G8H",
	"type": "order.in_progress",
	"created_at": "2026-07-09T12:00:00Z",
	"data": {
		"id": "ord_01HZX0OR1A2B3C4D5E6F7G8H",
		"customer_id": "cus_01HZX0C6Z3K4M5N6P7Q8R9S0",
		"destination": {
			"provider": "plusvibe",
			"workspace_id": "wrk_01HZX0PV1A2B3C4D5E6F7G8H"
		},
		"status": "in_progress",
		"domain_count": 1
	}
}

data.destination is the workspace target that received (or will receive) the mailboxes. Payloads never include provider credentials.

Event types

Orders

Event	Sent when
`order.in_progress`	Provisioning starts
`order.completed`	Full order finishes
`order.failed`	Order cannot be fulfilled
`order.cancel_scheduled`	Order or selected domains scheduled to cancel
`order.domains_cancelled`	Selected domains finish cancelling. Order may stay active.
`order.cancelled`	Full order finishes cancelling

Orders that need input appear in GET /orders/pending. There is no order.action_required event. Poll that endpoint.

Domains and imports

Event	Sent when
`domain_import.completed`	Every submitted domain imported successfully
`domain_import.action_required`	Some domains imported and others failed
`domain_import.failed`	Import run failed
`domain.forwarding_updated`	Forwarding job completes or partially succeeds
`domain.forwarding_failed`	Every domain in a forwarding job fails

Pool

Event	Sent when
`pool.claim.completed`	Attach finished
`pool.claim.failed`	Attach failed
`pool.release.completed`	Release finished
`pool.release.failed`	Release failed
`pool.replacement.pending`	Burned-domain replacement awaiting approval
`pool.replacement.started`	Replacement work started
`pool.replacement.completed`	Replacement finished
`pool.replacement.declined`	Replacement declined
`pool.replacement.failed`	Replacement failed

Swaps

Event	Sent when
`swap.created`	Domain or mailbox-name swap accepted
`swap.in_progress`	Swap work starts
`swap.completed`	Swap finishes
`swap.failed`	Swap cannot finish

Test and rotate

In the portal, send a test event or simulate a lifecycle. Test payloads include "test": true. Rotating the signing secret replaces the old value immediately and shows the new secret once. Update your receiver right away.

Verify the signature

Sign exactly:

<Peeker-Timestamp>.<Peeker-Event-Id>.<raw request body>

Use HMAC-SHA-256 with the listener secret. Compare the result to the hex after v1=. Use the raw body. Re-serializing JSON breaks the signature.

Node.js

import crypto from 'node:crypto';

export function verifyPeekerWebhook({ rawBody, eventId, timestamp, signature, secret }) {
	if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;
	if (!signature.startsWith('v1=')) return false;

	const expected = crypto
		.createHmac('sha256', secret)
		.update(`${timestamp}.${eventId}.${rawBody}`)
		.digest('hex');
	const provided = signature.slice(3);
	if (provided.length !== expected.length) return false;

	return crypto.timingSafeEqual(Buffer.from(provided), Buffer.from(expected));
}

Reject missing headers, bad signatures, and timestamps more than five minutes off your server clock.

Delivery and retries

Rule	Detail
Timeout	Return any `2xx` within 15 seconds
Retries	Up to five attempts for network failures, timeouts, `429`, and `5xx`
Terminal	Other `4xx` responses are not retried
Delivery	At least once. The same event can arrive more than once
Dedupe	Store `Peeker-Event-Id` before work. Keep IDs for at least 24 hours
Ordering	Events for the same resource can arrive out of order. Use `data.status`

See Async jobs for which endpoints emit which events.

Concepts

Webhooks

Request format

Event types

Orders

Domains and imports

Pool

Swaps

Test and rotate

Verify the signature

Delivery and retries

​Request format

​Event types

​Orders

​Domains and imports

​Pool

​Swaps

​Test and rotate

​Verify the signature

​Delivery and retries

Request format

Event types

Orders

Domains and imports

Pool

Swaps

Test and rotate

Verify the signature

Delivery and retries