Webhooks

Webhooks send HTTP POST requests to your endpoints when events occur. Deliveries are signed with HMAC-SHA256.

Supported events

Event	Trigger
snapshot.created	A new snapshot is created
snapshot.deleted	A snapshot is deleted
file.uploaded	A file is uploaded
file.deleted	A file is deleted
member.invited	A team member is invited
member.removed	A team member is removed

Register a webhook

POST /machine/webhooks

Roles: owner admin

{
  "url": "https://example.com/webhook",
  "events": ["snapshot.created", "file.uploaded"],
  "secret": "optional-custom-secret"
}

Field	Type	Required	Description
url	string	Yes	Endpoint URL
events	string[]	Yes	Event types to subscribe to
secret	string	No	Signing secret (auto-generated if omitted)

Response 201

{
  "id": "a1b2c3d4-...",
  "url": "https://example.com/webhook",
  "events": ["snapshot.created", "file.uploaded"],
  "secret": "the-signing-secret",
  "active": true
}

The secret is returned on creation for signature verification. See Webhook Signatures.

List webhooks

GET /machine/webhooks

Secrets are not included in list responses.

{
  "webhooks": [
    {
      "id": "a1b2c3d4-...",
      "url": "https://example.com/webhook",
      "events": ["snapshot.created"],
      "active": true,
      "createdAt": "2026-02-07T12:00:00.000Z"
    }
  ]
}

Get webhook details

GET /machine/webhooks/:id

Returns the webhook config and last 20 delivery attempts.

{
  "id": "a1b2c3d4-...",
  "url": "https://example.com/webhook",
  "events": ["snapshot.created"],
  "active": true,
  "createdAt": "2026-02-07T12:00:00.000Z",
  "recentDeliveries": [
    {
      "id": "delivery-uuid",
      "event": "snapshot.created",
      "responseStatus": 200,
      "success": true,
      "attemptedAt": "2026-02-07T12:05:00.000Z"
    }
  ]
}

Update a webhook

PATCH /machine/webhooks/:id

Roles: owner admin

Update URL, events, or active status. At least one field required.

{
  "url": "https://example.com/new-endpoint",
  "events": ["snapshot.created", "snapshot.deleted"],
  "active": false
}

Delete a webhook

DELETE /machine/webhooks/:id

Roles: owner admin

Deletes the webhook and all delivery logs.