​
Overview

Webhooks enable your application to set up event based actions. In this section, you’ll learn how to configure webhooks to receive updates from Steuerboard.

​
Events

  • File: A file has been created, updated or deleted.
  • File Comment: A file comment has been created
  • Task: A task has been created, updated or deleted.
  • Task Comment: A task comment has been created
  • Client: A client has been created, updated or deleted.
  • Workspace: A workspace has been created, updated or deleted.

​
Configuration

To configure webhooks, you need to create an endpoint in your Settings.
1

First Step

Visit your Steuerboard Dashboard.Don’t have an account?
We offer a free plan for testing. Just mail us at founders@steuerboard.net
If you want to use our App in production, please take a look at our Pricing page to book a call with us.
2

Second Step

Go to Settings -> API and click on “Create Webhook”.
3

Third Step

Enter a valid URL and select the events you want to receive.

​
Retries

Webhooks are retried 7 times with an exponential backoff. If the webhook fails 7 times, the endpoint will be disabled. You can re-enable the endpoint at any time in your dashboard.

​
Webhook Authentication

Webhook authentication ensures that incoming webhook requests are securely verified before processing. This allows consumers to trust that webhook events originate from a secure and verified source.

​
How It Works

Each webhook request sent from the server includes an X-Webhook-Signature header containing a SHA-256 HMAC signature of the request payload. This signature is generated using a secret key known only to the server and your application. When the consumer receives a webhook, they can use the signature provided in the X-Webhook-Signature header to verify that the request has not been tampered with. This is done by computing their own HMAC signature using the shared secret key and comparing it to the signature included in the header.

​
Verifying the Signature

  • Compute the HMAC SHA-256 signature using the payload and the shared secret key
  • Compare the computed signature to the X-Webhook-Signature header value
  • If they match, the request is verified as authentic. If they do not match, treat the request with caution or reject it
By verifying webhook signatures, consumers can ensure that webhook events received are secure and have not been altered during transmission.

​
Code Examples

Here’s how to verify webhook signatures in different programming languages:
handler.js
const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  // Parse the signature header
  const elements = signature.split(',');
  const sigData = {};
  
  for (const element of elements) {
    const [key, value] = element.split('=');
    sigData[key] = value;
  }
  
  // Extract timestamp and signature
  const timestamp = sigData.t;
  const expectedSignature = sigData.v1;
  
  if (!timestamp || !expectedSignature) {
    throw new Error('Invalid signature format');
  }
  
  // Create the payload string that was signed
  const signedPayload = `${timestamp}.${payload}`;
  
  // Compute the HMAC
  const computedSignature = crypto
    .createHmac('sha256', secret)
    .update(signedPayload)
    .digest('hex');
  
  // Compare signatures using a constant-time comparison
  return crypto.timingSafeEqual(
    Buffer.from(expectedSignature, 'hex'),
    Buffer.from(computedSignature, 'hex')
  );
}

// Express.js example
app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.headers['x-webhook-signature'];
  const payload = req.body.toString();
  const secret = process.env.WEBHOOK_SECRET; // Your webhook secret
  
  try {
    if (!verifyWebhookSignature(payload, signature, secret)) {
      return res.status(401).send('Invalid signature');
    }
    
    // Process the webhook
    const data = JSON.parse(payload);
    console.log('Verified webhook:', data);
    
    res.status(200).send('OK');
  } catch (error) {
    console.error('Webhook verification failed:', error);
    res.status(400).send('Bad request');
  }
});

​
Signature Format

The X-Webhook-Signature header contains multiple components separated by commas:
  • t=<timestamp>: Unix timestamp when the signature was generated
  • v1=<signature>: HMAC-SHA256 signature in hexadecimal format
  • alg=<algorithm>: The algorithm used (always hmac-sha256)
Example: t=1640995200,v1=a1b2c3d4...,alg=hmac-sha256