Skip to Content
Podyard

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:

ParamTypeDefaultMaxDescription
cursorstring——Pagination cursor
limitint50200Page 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 secret is 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_..."
}
FieldTypeRequiredDescription
urlstringyesHTTPS URL to deliver events to
eventsstring[]yesEvent types to subscribe to
secretstringnoHMAC 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 secret field 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 2xx within 10 seconds.

WHERE_TO_GO_NEXT

  • Keys — manage API keys.
  • Errors — full error code reference.