WEBHOOKS
List, create, and delete webhook subscriptions.
WEBHOOKS
Webhooks deliver event notifications to your application. Use them to react to pod lifecycle events without polling.
Base: https://api.podyard.dev/v1
GET /v1/webhooks — List webhooks
Headers: Authorization: Bearer <key>.
Query params:
| Param | Type | Default | Max | Description |
|---|---|---|---|---|
cursor | string | — | — | Pagination cursor |
limit | int | 50 | 200 | Page size |
Response 200:
{
"items": [
{
"id": "wh_01J...",
"url": "https://example.com/podyard-webhook",
"events": ["pod.created", "pod.destroyed", "exec.completed"],
"createdAt": "2026-01-15T10:30:00Z",
"lastDeliveredAt": "2026-01-15T12:00:00Z",
"lastError": null,
"active": true
}
],
"nextCursor": null
}Security: The webhook
secretis never returned by this endpoint. It is shown once at creation and must be stored securely.
POST /v1/webhooks — Create a webhook
Headers: Authorization: Bearer <key>, Content-Type: application/json, optional Idempotency-Key.
Body:
{
"url": "https://example.com/podyard-webhook",
"events": ["pod.created", "pod.destroyed", "exec.completed"],
"secret": "whsec_..."
}| Field | Type | Required | Description |
|---|---|---|---|
url | string | yes | HTTPS URL to deliver events to |
events | string[] | yes | Event types to subscribe to |
secret | string | no | HMAC signing secret. If omitted, the platform generates one. |
Supported events: pod.created, pod.destroyed, pod.error, pod.slept, pod.woken, exec.completed.
Coming soon:
snapshot.created,snapshot.deleted, and usage-threshold events.
Response 201:
{
"id": "wh_01J...",
"url": "https://example.com/podyard-webhook",
"events": ["pod.created", "pod.destroyed", "exec.completed"],
"secret": "whsec_...",
"createdAt": "2026-01-15T10:30:00Z",
"active": true
}⚠️ The
secretfield is returned ONLY in this response. Store it for signature verification. It is never available again.
Errors: 422 invalid_request (invalid URL, unknown event type).
DELETE /v1/webhooks/{id} — Delete a webhook
Headers: Authorization: Bearer <key>.
Response 204: empty body.
Errors: 404 not_found.
SIGNATURE_VERIFICATION
Every delivery includes:
X-Podyard-Signature: t=<unix_timestamp>,v1=<hmac_sha256_hex>
X-Podyard-Delivery: <delivery_id>Verify: hmac_sha256(secret, "<timestamp>.<raw_body>") must equal v1. Reject deliveries where t is older than 5 minutes.
DELIVERY_GUARANTEES
- At-least-once delivery.
- Retries: exponential backoff, up to 5 retries over 1 hour.
- Your endpoint must return
2xxwithin 10 seconds.