Webhook Setup

Webhooks allow Almirant to send automatic HTTP notifications to your server when events occur in your projects. Every time a work item is created, a task is moved between columns, or a sprint is closed, Almirant sends a POST request to the URL you configure with the event data.

This is useful for:

• Syncing Almirant with external tools (Slack, Discord, your own dashboard)
• Triggering CI/CD pipelines when a task changes status
• Feeding analytics or reporting systems
• Automating custom workflows outside of Almirant

Creating a webhook

1. Go to Settings > Webhooks in your project
2. Click Create webhook
3. Fill in the fields:

Field	Description	Example
URL	HTTPS endpoint that will receive the notifications	https://my-server.com/webhooks/almirant
Events	Event types that trigger the webhook	work_item.created, sprint.closed
Secret	Secret key to validate the authenticity of requests	Auto-generated, or you can define your own

4. Click Save

Important

The URL must be accessible from the internet and use HTTPS. Almirant will not send webhooks to unencrypted HTTP URLs (except localhost in development).

Available events

Select one or more events when creating the webhook:

Event	Triggered when...
work_item.created	A new work item is created
work_item.updated	Fields of a work item are modified (title, description, priority, etc.)
work_item.moved	A work item is moved between board columns
work_item.archived	A work item is archived
lead.created	A new lead is created in the CRM
lead.updated	Lead data is updated
lead.stage_changed	A lead changes stage in the funnel
sprint.created	A new sprint is created
sprint.closed	A sprint is closed

Tip

If you only need to react to board changes, select only the work_item.* events. The fewer events you subscribe to, the less traffic your server receives.

Verifying the webhook signature

Each request includes an HMAC-SHA256 signature in the X-Almirant-Signature header that allows you to verify that the request actually comes from Almirant and has not been tampered with.

How verification works

1. Almirant generates an HMAC-SHA256 hash of the request body using your secret as the key
2. It includes the hash in the X-Almirant-Signature header
3. Your server recalculates the hash with the same secret and compares them

Node.js example

import crypto from 'node:crypto';

function verifyWebhookSignature(body, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(body, 'utf8')
    .digest('hex');

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

// In your endpoint:
app.post('/webhooks/almirant', (req, res) => {
  const signature = req.headers['x-almirant-signature'];
  const rawBody = req.rawBody; // Body as string, not parsed

  if (!verifyWebhookSignature(rawBody, signature, process.env.WEBHOOK_SECRET)) {
    return res.status(401).json({ error: 'Invalid signature' });
  }

  const event = JSON.parse(rawBody);
  console.log('Event received:', event.type);

  // Process the event...

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

Python example

import hmac
import hashlib

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

Security

Always verify the signature before processing the event. Never trust webhook data without validating its authenticity. Use timingSafeEqual (or equivalent) to prevent timing attacks.

Viewing delivery logs

Each webhook maintains a delivery history that you can inspect to debug issues.

1. Go to Settings > Webhooks
2. Click on the webhook you want to inspect
3. In the Deliveries tab, you will see a list with:

Column	Description
Date	Exact time of the delivery
Event	Event type that triggered the delivery
Status	HTTP response code (200, 500, timeout, etc.)
Duration	Response time from your server

Click on any delivery to see the full details: sent headers, payload body, and your server's response.

Retries and failures

Almirant automatically retries failed deliveries with exponential backoff:

Attempt	Wait before retry
1	Immediate
2	1 minute
3	5 minutes
4	30 minutes
5	2 hours

A delivery is considered failed when:

• Your server responds with an HTTP status code >= 400
• Your server does not respond within 10 seconds (timeout)
• A connection to your server cannot be established

After 5 failed attempts, the delivery is marked as failed and will not be retried. You can manually resend it from the delivery log.

Note

Your server should respond with an HTTP 2xx status code (ideally 200) as quickly as possible. If you need to do lengthy processing, accept the webhook immediately and process the data asynchronously.

Disabling or deleting a webhook

• Disable: In the webhook list, use the toggle to temporarily disable it. Deliveries are paused but the configuration is preserved.
• Delete: Click the delete icon. This action is irreversible and also deletes the delivery history.