Webhook API

Overview

The Webhook API lets you trigger changelog generation programmatically from your deployment pipeline. When your deployment succeeds, you make a POST request to your unique webhook URL, and AutoChangelog fetches your recent commits from GitHub and generates a new entry.

Endpoint

Each repository has a unique webhook URL that looks like this:

POST https://autochangelog.com/api/v1/hooks/:webhook_uid

Find your actual webhook URL and secret in your repository settings on AutoChangelog. The webhook UID is a unique identifier for your repository, and the secret is used to sign requests for authentication.

Authentication

All webhook requests must be signed using HMAC-SHA256 to verify they're coming from your deployment pipeline. Compute a signature of the request body using your webhook secret, then include it in the X-Webhook-Signature header prefixed with sha256=.

Bash Example

# Your webhook secret (from repository settings)
SECRET="your-webhook-secret"

# Request body (JSON with optional parameters)
BODY='{"bump": "patch"}'

# Compute HMAC-SHA256 signature
SIGNATURE="sha256=$(echo -n "$BODY" | openssl dgst -sha256 -hmac "$SECRET" | cut -d' ' -f2)"

# Make the request
curl -X POST "https://autochangelog.com/api/v1/hooks/your-webhook-uid" \
  -H "Content-Type: application/json" \
  -H "X-Webhook-Signature: $SIGNATURE" \
  -d "$BODY"

JavaScript/Node.js Example

const crypto = require('crypto');

const secret = process.env.AUTOCHANGELOG_SECRET;
const webhookUrl = process.env.AUTOCHANGELOG_WEBHOOK_URL;
const body = JSON.stringify({ bump: 'patch' });

const signature = 'sha256=' + crypto
  .createHmac('sha256', secret)
  .update(body)
  .digest('hex');

const response = await fetch(webhookUrl, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Webhook-Signature': signature
  },
  body: body
});

console.log(await response.json());

Python Example

import hmac
import hashlib
import requests
import json
import os

secret = os.environ['AUTOCHANGELOG_SECRET']
webhook_url = os.environ['AUTOCHANGELOG_WEBHOOK_URL']
body = json.dumps({'bump': 'patch'})

signature = 'sha256=' + hmac.new(
    secret.encode(),
    body.encode(),
    hashlib.sha256
).hexdigest()

response = requests.post(
    webhook_url,
    headers={
        'Content-Type': 'application/json',
        'X-Webhook-Signature': signature
    },
    data=body
)

print(response.json())

Request Parameters

Send a JSON body with any of these optional parameters. If you send an empty body, AutoChangelog will auto-increment the patch version from your last entry.

Response

On success, you'll receive a 201 Created response with details about the entry being generated:

{
  "message": "Release changelog generation started",
  "entry_id": 123,
  "version": "v1.2.1",
  "auto_publish": false
}

If there are no new commits since your last changelog, you'll receive a 200 OK response:

{
  "message": "No new commits since last changelog",
  "last_version": "v1.2.0",
  "last_commit": "abc123def456...",
  "next_version": "v1.2.1"
}

Error Responses

The API returns standard HTTP status codes for errors. A 401 means your signature is missing or invalid. A 403 means you've exceeded your monthly limit on the free plan. A 404 means the webhook URL is invalid or the repository has been disabled. A 409 means an entry already exists for the requested version. A 422 means your version format is invalid or other parameters are malformed.

Webhook Info Endpoint

You can send a GET request to your webhook URL to verify it's configured correctly without triggering a changelog. This returns information about the webhook configuration and accepted parameters.

curl https://autochangelog.com/api/v1/hooks/your-webhook-uid

Security Best Practices

Keep your webhook secret safe by storing it in environment variables or a secrets manager, never in your code or version control. Always use HTTPS since HTTP is not supported. If you suspect your secret was compromised, regenerate it from your repository settings on AutoChangelog. Make sure to check the HTTP status code in your deployment script to catch any errors.

Rate Limits

The free plan allows 10 changelog entries per month. Pro and Team plans have unlimited entries. Rate limiting is applied per repository. If you exceed your limit, you'll receive a 403 response until your limit resets or you upgrade your plan.