​
Webhooks API

Subscribe to platform events and receive HTTP notifications when resources change.

​
List Webhooks

GET /api/v1/webhooks

[
  {
    "id": "wh_a1b2c3d4",
    "url": "https://example.com/webhook",
    "events": [
      "droplet.created",
      "droplet.destroyed",
      "app.deployed"
    ],
    "active": true,
    "created_at": "2024-01-15T10:30:00Z"
  }
]

​
Create a Webhook

POST /api/v1/webhooks
​
url
string
required
HTTPS endpoint to receive events
​
events
string[]
required
Event types to subscribe to
​
secret
string
Shared secret for request signing
{
  "url": "https://example.com/webhook",
  "events": ["droplet.created", "app.deployed"],
  "secret": "whsec_your-signing-secret"
}

​
Update a Webhook

PATCH /api/v1/webhooks/{id}

​
Delete a Webhook

DELETE /api/v1/webhooks/{id}

​
Webhook Deliveries

View delivery history and status: 
GET /api/v1/webhook/deliveries

[
  {
    "id": "del_001",
    "webhook_id": "wh_a1b2c3d4",
    "event": "droplet.created",
    "status_code": 200,
    "success": true,
    "delivered_at": "2024-01-15T10:30:05Z"
  }
]

​
Event Types

EventDescription
droplet.createdA new Droplet was created
droplet.destroyedA Droplet was deleted
droplet.power_offA Droplet was powered off
droplet.power_onA Droplet was powered on
app.createdA new App was created
app.deployedAn App was deployed
app.destroyedAn App was deleted
volume.createdA Volume was created
volume.attachedA Volume was attached
volume.detachedA Volume was detached
database.createdA Database was created
database.destroyedA Database was deleted
backup.completedA backup job completed
backup.failedA backup job failed

​
Webhook Payload

{
  "event": "droplet.created",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    "id": "dpl_a1b2c3d4",
    "name": "web-server-01",
    "status": "provisioning"
  }
}

​
Verifying Signatures

If a secret is configured, each webhook delivery includes an X-Signature-256 header with an HMAC-SHA256 signature of the request body.