Webhooks

Receive real-time HTTP callbacks whenever specific events occur within Aevum News. Build automated workflows, trigger alerts, or sync data without polling.

Overview

Aevum News webhooks allow your application to subscribe to real-time events. When an event triggers, we send a POST request to your configured endpoint with a JSON payload containing the event type, timestamp, and relevant data.

💡

Webhooks are the most efficient way to integrate with Aevum News. Avoid polling APIs and reduce latency by receiving events the moment they happen.

Getting Started

Create an Endpoint

Build an HTTPS endpoint that can accept POST requests and respond with a 200 OK status.

Configure in Dashboard

Navigate to Settings → Webhooks in your Aevum News dashboard. Click Add Webhook and enter your endpoint URL.

Select Events

Choose which events you want to subscribe to. You can modify these at any time.

Verify & Go Live

We'll send a webhook.verified event to confirm your endpoint is reachable. Handle it to activate delivery.

Available Events

Event	Description
`story.created`	A new article draft has been created by an editor.
`story.published`	An article has been published and is now live.
`story.updated`	Content or metadata for an existing article was modified.
`breaking.triggered`	A breaking news alert has been issued.
`newsletter.sent`	The daily or weekly digest was successfully dispatched.
`webhook.failed`	A previous webhook delivery failed after all retries.

Request Format

All webhook payloads are sent as application/json via HTTPS. Each request includes standard headers for identification and verification.

Headers

POST /your-endpoint HTTP/1.1
Host: yourdomain.com
Content-Type: application/json
X-Aevum-Event: story.published
X-Aevum-Signature: sha256=abc123...
X-Aevum-Timestamp: 1704067200
User-Agent: Aevum-Webhooks/1.0

Example Payload

{
  "event": "story.published",
  "id": "evt_8f3k29d1m4",
  "timestamp": "2025-01-15T14:32:10Z",
  "data": {
    "story_id": "art_992x7m",
    "title": "Global Climate Summit Reaches Historic Accord",
    "slug": "/world/climate-summit-accord-2025",
    "author": "Elena Rodriguez",
    "category": "world-affairs",
    "url": "https://aevum.news/world/climate-summit-accord-2025"
  },
  "metadata": {
    "region": "eu-west-1",
    "delivery_attempt": 1
  }
}

Security & Verification

Every webhook request is signed using HMAC-SHA256. Verify signatures to ensure requests originate from Aevum News.

⚠️

Always verify the X-Aevum-Signature header before processing payloads. Never skip validation in production.

Verification Process

Retrieve the X-Aevum-Signature and X-Aevum-Timestamp headers.
Concatenate ${timestamp}.${raw_body}.
Generate an HMAC-SHA256 signature using your webhook secret.
Compare the computed signature with the received one using constant-time comparison.

Node.js Verification

const crypto = require('crypto');

function verifySignature(rawBody, signature, timestamp, secret) {
  const hmac = crypto.createHmac('sha256', secret);
  const digest = hmac.update(`${timestamp}.${rawBody}`).digest('hex');
  const expected = `sha256=${digest}`;
  return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
}

Retry Policy & Reliability

If your endpoint doesn't respond with a 2xx status within 5 seconds, we automatically retry delivery.

Attempts: 3 retries per event
Backoff: Exponential (5s → 30s → 5m)
Dead Letter: Failed payloads are logged for 7 days
Idempotency: Events include a unique id field. Store processed IDs to avoid duplicates.

📦

Webhooks are best-effort. For critical workflows, combine webhooks with our REST API to reconcile state.

Testing & Debugging

Use our built-in tools to validate your integration before going live.

Webhook Tester: Dashboard provides a temporary endpoint to inspect payloads in real-time.
Event Simulator: Manually trigger any event type from the webhook settings page.
Delivery Logs: View request/response pairs, status codes, and latency metrics for every delivery.

Third-party tools like webhook.site or RequestBin work well for local development.

FAQ

Do I need HTTPS for my webhook endpoint?

Yes. All webhook deliveries use HTTPS. HTTP endpoints will be rejected during verification.

What's the maximum payload size?

Standard payloads are under 5KB. Breaking news or media-heavy events may reach 50KB. Ensure your server handles up to 100KB.

How do I handle timezone differences?

All timestamps use ISO 8601 format in UTC. Convert to your local timezone server-side.

Can I pause webhook delivery?

Yes. Use the toggle switch in the dashboard to pause delivery without deleting your configuration or secrets.