Webhooks

Webhooks let you receive HTTP callbacks when events occur in your GolemDrive account. Instead of polling the API to check for changes, GolemDrive pushes events to a URL you specify.

Use cases

• Trigger a build pipeline when a file is uploaded
• Log download activity to an external analytics system
• Send a Slack notification when someone accesses a share link
• Sync file metadata with an external database
• Audit account changes in real time

Setting up a webhook

From the dashboard

1. Go to Account Settings > Webhooks
2. Click Add Webhook
3. Enter the URL where you want to receive events
4. Select which event types to subscribe to
5. Save

GolemDrive will send a test event to your URL to verify it’s reachable.

From the API

curl -X POST https://api.golemdrive.com/api/v1/webhooks/ \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-server.com/webhook",
    "events": ["file.uploaded", "share.accessed"]
  }'

Event types

Event	Triggered when
file.uploaded	A file finishes uploading
file.downloaded	A file is downloaded
file.deleted	A file is deleted
file.moved	A file is moved to a different folder
file.renamed	A file is renamed
share.created	A new share link is created
share.accessed	Someone opens a share link
share.downloaded	Someone downloads a file through a share link
share.revoked	A share link is disabled or deleted
team.member_joined	A new member joins a team
team.member_left	A member leaves a team

Payload format

Each webhook delivery sends a JSON POST request to your URL:

{
  "event": "file.uploaded",
  "timestamp": "2026-03-26T14:30:00Z",
  "data": {
    "file_id": "abc123",
    "file_name": "report.pdf",
    "folder_id": "def456",
    "size_bytes": 2048576
  },
  "webhook_id": "wh_789",
  "delivery_id": "del_012"
}

The data field varies depending on the event type. Each event type’s specific payload is documented in the API reference.

Signature verification

Every webhook delivery includes a signature header so you can verify it came from GolemDrive and wasn’t tampered with:

X-GolemDrive-Signature: sha256=a1b2c3d4e5f6...

To verify:

1. Get the webhook secret assigned when you created the webhook
2. Compute an HMAC-SHA256 of the raw request body using your secret
3. Compare the result to the value in the X-GolemDrive-Signature header

import hmac
import hashlib

def verify_webhook(payload_body, signature_header, secret):
    expected = hmac.new(
        secret.encode(),
        payload_body,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(f"sha256={expected}", signature_header)

Never process a webhook payload without verifying the signature first.

Payload encryption

Webhook payloads are encrypted at rest on GolemDrive’s servers. This means that even internally, stored webhook delivery records are protected. The payloads are decrypted only at the moment of delivery to your endpoint.

Retry logic

If your endpoint returns a non-2xx status code or doesn’t respond within 30 seconds, GolemDrive retries the delivery automatically:

Attempt	Delay
1st retry	1 minute
2nd retry	5 minutes
3rd retry	30 minutes
4th retry	2 hours
5th retry	12 hours

After 5 failed retries, the delivery is marked as failed. You can view failed deliveries in Account Settings > Webhooks and manually retry them.

Testing webhooks

You can send a test event from the dashboard to verify your endpoint is working:

1. Go to Account Settings > Webhooks
2. Click on an existing webhook
3. Click Send Test Event
4. Check your endpoint for the test payload

The test event uses the event type webhook.test with sample data so you can verify your integration end to end without triggering a real event.

Managing webhooks

List active webhooks

curl https://api.golemdrive.com/api/v1/webhooks/ \
  -H "Authorization: Bearer YOUR_TOKEN"

Update a webhook

curl -X PUT https://api.golemdrive.com/api/v1/webhooks/{id} \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "events": ["file.uploaded", "file.deleted", "share.created"]
  }'

Delete a webhook

curl -X DELETE https://api.golemdrive.com/api/v1/webhooks/{id} \
  -H "Authorization: Bearer YOUR_TOKEN"

Tips

• Use a service like webhook.site during development to inspect payloads before building your handler
• Always respond with a 200 status quickly — do heavy processing asynchronously after acknowledging receipt
• Store the delivery_id from each payload to handle deduplication, in case a retry delivers the same event twice
• If your endpoint will be temporarily unavailable, disable the webhook in settings rather than letting deliveries fail and retry