Webhooks

Webhooks

Receive signed infrastructure events and reconcile current resource state.

Webhooks deliver infrastructure event notifications to HTTPS receivers. Events report changes; the API remains the source for current resource configuration and operation state.

Create an endpoint

Open Settings → Integrations → Webhooks, enter the receiver URL, select organization or project scope, and choose event types. The receiver must have a trusted TLS certificate and accept POST requests with JSON bodies.

Event families include droplet.created, droplet.state_changed, droplet.preempted, node.health_changed, operation.completed, backup.completed, and backup.failed. Subscribe only to the events and scope needed by the integration.

Payload

An operation-completion event identifies the operation and its terminal state:

JSON
{
  "id": "evt_operation01",
  "type": "operation.completed",
  "created_at": "2026-05-09T10:00:12Z",
  "organization_id": "org_main",
  "project_id": "prj_payments",
  "data": {
    "operation_id": "op_create01",
    "resource_id": "drp_web01",
    "state": "succeeded"
  }
}

The event ID stays the same across delivery retries. Delivery attempts have separate attempt IDs. Project-independent events can have project_id=null. New payload fields can be added; receivers should ignore unused fields.

Verify signatures

The endpoint configuration issues a signing secret once. Deliveries contain Infra-Event-Id, Infra-Timestamp, and Infra-Signature headers. The signature is v1= followed by the lowercase hexadecimal HMAC-SHA256 of the timestamp, a period, and the exact request body bytes.

Verify the signature before parsing or acting on the payload. Compare signatures with a constant-time operation and reject timestamps more than 300 seconds from the receiver's clock. Keep clocks synchronized. A retry receives a new delivery timestamp and signature while preserving the event ID.

Acknowledge and process

Return a 2xx response after durably recording the event for processing. The default delivery timeout is 10 seconds. Long infrastructure work should run outside the receiver's request handler.

Deliveries can be repeated or arrive out of order. Deduplicate by event ID and read the current resource or operation before acting. An older running event can arrive after a newer terminal event; it must not move local state backwards.

Retries and failures

Transport failures, timeouts, 429, and 5xx responses are retried with increasing delay for up to 24 hours. Other 4xx responses mark the attempt as rejected without automatic retries. Redirects are not followed.

Open Settings → Integrations → Webhooks, select the endpoint, and inspect Deliveries for receiver status, attempt time, and next retry. Correct the receiver error before replaying the retained delivery. Replay keeps the original event ID. The receiver should acknowledge a completed event without repeating its side effects, or resume a failed local processing job.

Rotation and deletion

Use the signing-rotation operation to create a replacement secret and select its overlap period. Install it at the receiver while the old version is still accepted. Confirm a delivery verifies with the new version, then stop accepting the old secret when the overlap ends.

To stop new attempts, disable the endpoint under Settings → Integrations → Webhooks → Endpoint. Events already processed by the receiver remain applied.

Use API authentication for receiver-side API calls and Alerts when routing conditions rather than raw infrastructure events.

Use Webhook API to inspect attempts, rotate signing versions, and request retained-event replay. Receiver deduplication includes a signature verification example and separates durable receipt from completed downstream processing.