Webhook endpoints

A webhook endpoint is a URL on your server that Phew sends events to. Each endpoint subscribes to the event types you choose and has its own signing secret or key.

Delivery

• Phew sends a POST with a JSON event body and waits up to 10 seconds for a 2xx.
• Delivery is at least once. Use Phew-Event-Id to ignore duplicates.
• Events can arrive out of order. Use created_at on the event, or retrieve the object, if order matters.
• Failed deliveries are retried with exponential backoff for up to 3 days. After that the event is marked failed and can be redelivered on request.
• An endpoint that keeps failing for 3 days is disabled, and we email your technical contact.

Always verify the signature before acting on an event.

Create an endpoint

POST api.getphew.com/v1/webhook_endpoints webhooks:manage

Request body

url string required

HTTPS URL. Must have a valid public certificate.

events array required

Event types to receive, or ["*"] for all.

signing enum

hmac_sha256 (default) or ed25519_rfc9421. See Webhook verification.

description string

For your own reference.

Response 201

{
  "id": "whe_01JDD2G4J6L8N0Q2S4U6W8Y0A2",
  "object": "webhook_endpoint",
  "url": "https://shop.example/phew/webhooks",
  "events": ["policy.cancelled", "claim.resolved", "settlement.statement.created"],
  "signing": "hmac_sha256",
  "secret": "whsec_9mF2...",
  "status": "enabled",
  "created_at": "2026-10-23T14:01:12Z"
}

Caution

secret is only returned when the endpoint is created and when you roll it. Store it in your secrets manager.

Manage endpoints

GET api.getphew.com/v1/webhook_endpoints webhooks:manage

GET api.getphew.com/v1/webhook_endpoints/{id} webhooks:manage

PATCH api.getphew.com/v1/webhook_endpoints/{id} webhooks:manage

DELETE api.getphew.com/v1/webhook_endpoints/{id} webhooks:manage

PATCH accepts url, events, description and status (enabled or disabled).

Roll the secret

POST api.getphew.com/v1/webhook_endpoints/{id}/roll_secret webhooks:manage

Returns a new secret. Optionally send expires_in (seconds, up to 7 days) to keep the old one valid in parallel; during that time the Phew-Signature header carries a v1 signature for each.

Send a test event

POST api.getphew.com/v1/webhook_endpoints/{id}/test webhooks:manage

Sends a ping event to the endpoint and returns the status code and timing of your response.