Skip to main content

​
Overview

Webhooks let your server receive real-time notifications when activity occurs on an Aptly board. Instead of polling the API for changes, Aptly sends an HTTP POST request to a URL you specify whenever a relevant event occurs.

​
Setup

  1. Open the board you want to monitor
  2. Click Card Sources in the board toolbar
  3. Select API and enable the REST API if not already on
  4. Paste your server endpoint into the Webhook URL field
  5. Copy the Webhook Signing Key for use in your handler
  6. Click Save

​
Events

Aptly sends a webhook for the following events:
  • Card created
  • Card updated
  • Card deleted
  • Comment posted on a card
  • File uploaded to a card

​
Payload

The request body is a JSON object containing key/value pairs where the key is the name of a board field and the value is its current value. The exact fields present depend on your board structure. 
{
  "Name": "John Smith",
  "Status": "New",
  "Email": "john@example.com"
}

​
Verifying the signature

Every webhook request includes your Webhook Signing Key as an x-signingKey header. Your server can read this header and compare it against the key shown in your Card Sources panel to confirm the request is genuinely from Aptly. 
function verifyWebhook(req, signingKey) {
  return req.headers["x-signingkey"] === signingKey;
}
If the header does not match your expected key, reject the request before processing the payload.
If your Webhook Signing Key is ever exposed, return to Card Sources and regenerate it immediately. This invalidates the old key.

​
Responding to webhooks

Your server must return a 200 HTTP status within 60 seconds. If Aptly does not receive a 200, the delivery is marked as failed. Aptly will continue retrying the webhook indefinitely until you update or remove the Webhook URL. Return your 200 response as quickly as possible. If you need to do heavy processing, acknowledge the webhook immediately and handle the work asynchronously.

​
Ordering

Webhooks are delivered in the order that events occur on the board.

​
Rate limits

There are no rate limits on webhook delivery.

​
Testing

To test your webhook handler, create a test card on the board and trigger a delivery by making a modification to it. Your server should receive the webhook within a few seconds. For local development, use a tool like ngrok to expose a local port to the internet, then point the Webhook URL at your ngrok tunnel.