Webhooks

Before You Begin

• Organization or Team Owner permissions - You need admin access to configure webhooks
• A webhook endpoint - A publicly accessible URL that can receive POST requests
• HTTPS support - Your endpoint must support HTTPS (recommended)
• Ability to verify signatures - Your endpoint should validate webhook signatures for security

1. Navigate to Organization Settings from the main menu
2. Click on the Webhooks tab
3. Click Create Webhook button
4. Enter your webhook URL (e.g., https://api.yourapp.com/webhooks)
5. Select the events you want to subscribe to
6. Optionally add a description for easy identification
7. Click Create
8. Important: Copy and save the webhook secret - it's only shown once!

1. Go to your Team Dashboard
2. Click Manage Team Webhooks in the Webhook Integrations section
3. Follow the same steps as organization webhooks above
4. Team webhooks receive events specific to that team only

PHP/Laravel

Route::post('/webhook', function (Request $request) {
    // Handle validation challenge
    if ($request->input('type') === 'validation') {
        return response()->json([
            'challenge' => $request->input('challenge')
        ]);
    }

    // Handle actual webhook events...
    // (verify signature, process event, etc.)
});

Node.js/Express

app.post('/webhook', (req, res) => {
    // Handle validation challenge
    if (req.body.type === 'validation') {
        return res.status(200).json({
            challenge: req.body.challenge
        });
    }

    // Handle actual webhook events...
});

Python/Flask

@app.route('/webhook', methods=['POST'])
def webhook():
    payload = request.get_json()

    # Handle validation challenge
    if payload.get('type') == 'validation':
        return jsonify({'challenge': payload['challenge']}), 200

    # Handle actual webhook events...

Every webhook includes a signature in the X-PlanningForge-Signature header. This signature is created using HMAC-SHA256 with your webhook secret.

PHP

function verifyWebhookSignature($payload, $signature, $secret) {
    $expectedSignature = 'sha256=' . hash_hmac(
        'sha256',
        json_encode($payload),
        $secret
    );

    return hash_equals($expectedSignature, $signature);
}

// Usage
$payload = json_decode($request->getContent(), true);
$signature = $request->header('X-PlanningForge-Signature');
$secret = 'your-webhook-secret';

if (!verifyWebhookSignature($payload, $signature, $secret)) {
    abort(401, 'Invalid signature');
}

Node.js

const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
    const expectedSignature = 'sha256=' + crypto
        .createHmac('sha256', secret)
        .update(JSON.stringify(payload))
        .digest('hex');

    return crypto.timingSafeEqual(
        Buffer.from(signature),
        Buffer.from(expectedSignature)
    );
}

Every webhook delivery includes these HTTP headers:

If your endpoint fails to respond with a 2xx status code or times out, PlanningForge automatically retries the delivery with increasing delays between attempts:

This exponential backoff strategy gives your endpoint time to recover from temporary issues while minimizing load during outages.

To protect both systems, webhooks are automatically deactivated after 5 consecutive delivery failures.

1. Go to webhook.site - you'll get a unique URL
2. Copy the unique URL provided
3. Create a webhook in PlanningForge using that URL
4. Click the Send Test button on your webhook
5. View the request details on webhook.site