Webhooks

Webhooks let your systems react to events on Kapable in real time. Instead of polling the API, Kapable sends an HTTP POST to your endpoint whenever something happens.

Event Types

Payload Format

Every webhook POST sends a JSON body:

{
  "id": "evt_01J5K...",
  "type": "app.deployed",
  "created_at": "2026-05-21T10:30:00Z",
  "org_id": "d3f1a2b4-...",
  "data": {
    "app_id": "a1b2c3d4-...",
    "app_name": "my-app",
    "version": "v1.4.2",
    "deployed_by": "alice@example.com"
  }
}

The data object varies by event type. See the API Reference for the full schema of each event.

Setting Up an Endpoint

Your webhook endpoint must:

1. Accept POST requests with a JSON body
2. Return a 2xx status within 10 seconds to acknowledge receipt
3. Be publicly reachable via HTTPS (plain HTTP is rejected)

Example endpoint in Node.js:

app.post('/webhooks/kapable', (req, res) => {
  const event = req.body;
  console.log(`Received ${event.type}`, event.data);

  // Process the event asynchronously
  processEvent(event).catch(console.error);

  // Acknowledge immediately
  res.status(200).json({ received: true });
});

Verifying Signatures

Every webhook includes an X-Kapable-Signature header containing an HMAC-SHA256 signature of the request body, signed with your webhook secret.

Always verify the signature before processing:

import hmac
import hashlib

def verify_signature(payload_body, signature_header, secret):
    expected = hmac.new(
        secret.encode('utf-8'),
        payload_body,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(f"sha256={expected}", signature_header)

const crypto = require('crypto');

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

Retry Policy

If your endpoint doesn't return a 2xx response, Kapable retries with exponential backoff:

After 3 failed retries, the event is marked as failed. You can view failed deliveries in the Send Audit page.

Testing

During development, use a tunnel or request-inspection tool:

1. ngrok — expose your local server: ngrok http 3000
2. webhook.site — inspect payloads without any code
3. Kapable test events — use the "Send Test" button in webhook configuration to fire a sample event

Best Practices

• Process asynchronously. Acknowledge the webhook immediately (return 200), then process the event in a background job. This prevents timeouts.
• Be idempotent. You may receive the same event more than once (during retries). Use the id field to deduplicate.
• Log everything. Store raw payloads for debugging. The Send Audit page also keeps a record.
• Handle unknown events. New event types may be added. Your handler should ignore types it doesn't recognise rather than failing.
• Rotate secrets regularly. You can regenerate your webhook secret in the console without downtime — both old and new secrets are valid for 24 hours during rotation.

Console Configuration

Next Steps

Next

Getting Started · Authentication