Webhooks

The Webhooks API lets you subscribe to real-time event notifications delivered to your endpoints via HTTP POST. When a deployment changes status or a waitlisted GPU becomes available, the system sends a signed payload to your registered URL.

Base URL: https://gpu.huddleapis.com/api/v1

Create a Webhook

curl -X POST -H "X-API-Key: mk_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-server.com/webhook",
    "events": [
      "deployment.running",
      "deployment.error",
      "deployment.deleted"
    ]
  }' \
  https://gpu.huddleapis.com/api/v1/webhooks

Response:

{
  "code": "OK",
  "data": {
    "id": "wh_abc123",
    "url": "https://your-server.com/webhook",
    "secret": "whsec_a1b2c3d4e5f6...signing_secret_here",
    "events": [
      "deployment.running",
      "deployment.error",
      "deployment.deleted"
    ],
    "is_active": true,
    "created_at": "2026-04-03T10:00:00Z"
  }
}

Save your signing secret

The webhook secret is returned only once at creation time. You need it to verify that incoming payloads are authentic. Store it securely.

Events

Event	Description
`deployment.ordered`	A new deployment has been accepted and queued
`deployment.provisioning`	Hardware is being allocated and configured
`deployment.running`	Deployment is online and accessible via SSH
`deployment.offline`	Deployment has gone offline
`deployment.error`	Deployment encountered an error
`deployment.deleted`	Deployment has been permanently removed
`deployment.failed_no_capacity`	Deploy failed because no GPU capacity was available
`gpu.available`	A previously unavailable GPU type is now available (for Waitlist users)

Webhook Payload

When an event fires, your endpoint receives a POST request with a JSON payload:

{
  "event": "deployment.running",
  "deployment_id": "dep_abc123",
  "provider_id": "verda-xyz",
  "status": "running",
  "cluster_type": "1H100.80S.30V",
  "hostname": "my-training-run",
  "image": "ubuntu-22.04-cuda-12.4-cluster",
  "location": "FIN-01",
  "ip": "185.123.45.67",
  "ssh_user": "root",
  "specs": {
    "gpu_model": "H100",
    "gpu_count": 1,
    "gpu_vram_gb": 80,
    "vcpu_count": 30,
    "ram_gb": 120,
    "price_per_hr": 1.71
  },
  "timestamp": "2026-04-03T10:05:00Z"
}

Signature Verification

All webhook payloads are signed using HMAC-SHA256. The signature is sent in the X-Webhook-Signature header. Always verify the signature before processing the payload.

Node.js

const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload, 'utf8')
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

// In your webhook handler
app.post('/webhook', (req, res) => {
  const signature = req.headers['x-webhook-signature'];
  const isValid = verifyWebhook(
    JSON.stringify(req.body),
    signature,
    process.env.WEBHOOK_SECRET
  );

  if (!isValid) {
    return res.status(401).send('Invalid signature');
  }

  // Process the event
  console.log('Event:', req.body.event);
  res.status(200).send('OK');
});

Python

import hmac
import hashlib

def verify_webhook(payload: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode('utf-8'),
        payload,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(signature, expected)

# In your webhook handler (Flask example)
@app.route('/webhook', methods=['POST'])
def handle_webhook():
    signature = request.headers.get('X-Webhook-Signature')
    if not verify_webhook(request.data, signature, WEBHOOK_SECRET):
        return 'Invalid signature', 401

    event = request.json
    print(f"Event: {event['event']}")
    return 'OK', 200

Managing Webhooks

List webhooks

curl -H "X-API-Key: mk_your_key" \
  https://gpu.huddleapis.com/api/v1/webhooks

Update a webhook

curl -X PUT -H "X-API-Key: mk_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "events": ["deployment.running", "deployment.deleted"],
    "is_active": true
  }' \
  https://gpu.huddleapis.com/api/v1/webhooks/wh_abc123

Delete a webhook

curl -X DELETE -H "X-API-Key: mk_your_key" \
  https://gpu.huddleapis.com/api/v1/webhooks/wh_abc123

Best Practices

Respond with 2xx quickly — process events asynchronously. The webhook delivery system expects a fast response.
Verify signatures — always validate the X-Webhook-Signature header to ensure payloads are authentic.
Handle duplicates — in rare cases, the same event may be delivered more than once. Use the deployment_id + event + timestamp to deduplicate.
Use HTTPS endpoints — webhook URLs must use HTTPS to ensure payloads are encrypted in transit.

Next Steps

Set up Deployments to start receiving events
Use the Waitlist with gpu.available events
Review the GPU API Overview for the full picture

Webhooks

On this page