Webhooks

Webhooks

Receive real-time notifications for build events and project updates.

Overview

Webhooks allow you to receive HTTP POST notifications when specific events occur in your DeskForge projects. This enables you to integrate DeskForge with your CI/CD pipeline, notification systems, or custom workflows.

Use Cases: Notify your team on Slack when builds complete, trigger deployments, update status pages, or log events to analytics.

Webhook Events

DeskForge sends webhook notifications for the following events:

build.queued

A new build has been queued

build.started

A build has started processing

build.succeeded

A build completed successfully

build.failed

A build failed with errors

project.created

A new project was created

project.updated

A project was updated

project.deleted

A project was deleted

Create Webhook

Register a webhook endpoint to receive event notifications.

POST/webhooks

Request Body

urlstring (required)

Your webhook endpoint URL (must be HTTPS)

eventsarray (required)

List of events to subscribe to

secretstring (optional)

Secret for webhook signature verification

Request

curl -X POST https://api.deskforge.app/webhooks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/webhooks/deskforge",
    "events": ["build.succeeded", "build.failed"],
    "secret": "your_webhook_secret"
  }'

Response

{
  "id": "wh_abc123",
  "url": "https://your-app.com/webhooks/deskforge",
  "events": ["build.succeeded", "build.failed"],
  "active": true,
  "createdAt": "2024-01-20T10:00:00Z"
}

Webhook Payload

When an event occurs, DeskForge sends a POST request to your webhook URL with the following structure:

Example Payload

{
  "id": "evt_xyz789",
  "type": "build.succeeded",
  "createdAt": "2024-01-20T10:15:00Z",
  "data": {
    "build": {
      "id": "build_xyz789",
      "projectId": "proj_abc123",
      "version": "1.0.0",
      "platform": "mac",
      "arch": "arm64",
      "status": "success",
      "artifactUrl": "https://cdn.deskforge.app/builds/...",
      "duration": 840
    },
    "project": {
      "id": "proj_abc123",
      "name": "My Desktop App"
    }
  }
}

Webhook Security

Verify webhook requests using the signature header to ensure they're from DeskForge.

Signature Verification

Each webhook request includes a X-DeskForge-Signature header containing an HMAC SHA-256 signature.

// Node.js example
const crypto = require('crypto');

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

// Express middleware
app.post('/webhooks/deskforge', (req, res) => {
  const signature = req.headers['x-deskforge-signature'];
  const isValid = verifyWebhook(req.body, signature, process.env.WEBHOOK_SECRET);
  
  if (!isValid) {
    return res.status(401).send('Invalid signature');
  }
  
  // Process webhook
  console.log('Event:', req.body.type);
  res.status(200).send('OK');
});

List Webhooks

Retrieve all webhooks for your account.

GET/webhooks

Request

curl -X GET https://api.deskforge.app/webhooks \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "webhooks": [
    {
      "id": "wh_abc123",
      "url": "https://your-app.com/webhooks/deskforge",
      "events": ["build.succeeded", "build.failed"],
      "active": true,
      "createdAt": "2024-01-20T10:00:00Z"
    }
  ],
  "total": 1
}

Delete Webhook

Remove a webhook endpoint.

DELETE/webhooks/:webhookId

Request

curl -X DELETE https://api.deskforge.app/webhooks/wh_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "id": "wh_abc123",
  "deleted": true,
  "message": "Webhook deleted successfully"
}

Best Practices

✓ Use HTTPS

Always use HTTPS endpoints for webhooks to ensure secure transmission.

✓ Verify Signatures

Always verify the webhook signature to prevent unauthorized requests.

✓ Respond Quickly

Return a 200 status code quickly. Process webhooks asynchronously if needed.

✓ Handle Retries

DeskForge retries failed webhooks up to 3 times. Make your endpoint idempotent.

✓ Monitor Failures

Set up monitoring to detect webhook failures and investigate issues promptly.