Webhooks
Configure event-driven webhooks with HMAC-SHA256 signature verification, delivery logs, and retry policy.
Webhooks
Webhooks are HTTP callbacks that IANews sends to your server when specific events occur. Use them to integrate IANews with custom workflows, third-party platforms, Slack bots, or internal tools.
Supported events
| Event | Trigger | Key payload fields |
|---|---|---|
article.published | An article is published to a CMS target | article_id, title, target, published_url |
article.updated | An article's content is updated | article_id, title, changed_fields |
article.deleted | An article is deleted | article_id, title |
trend.alert | An alert condition is matched | alert_id, trend_id, trend_name, score, condition |
brief.completed | A brief finishes execution | brief_id, article_ids, article_count |
Every payload also includes timestamp (ISO 8601), event (the event type string), and site_id identifying the originating site.
Create a webhook
Open the Webhooks settings
Navigate to Sites -- select your site -- Webhooks. Click New Webhook.
Enter the endpoint URL
Provide the HTTPS URL of your server endpoint that will receive webhook payloads. HTTP endpoints are not accepted -- your server must support TLS.
Select events
Check the events you want to subscribe to. You can select one or more events per webhook. Create multiple webhooks if different events need to reach different endpoints.
Copy the signing secret
IANews generates a unique signing secret for this webhook. Copy it and store it securely on your server -- you need it to verify incoming payloads.
Test the webhook
Click Send Test. IANews sends a ping event to your endpoint. Verify that your server responds with a 200 status code. The delivery result appears in the webhook settings.
Save and activate
Click Save. The webhook is now active and fires on the selected events.
HMAC-SHA256 signature verification
Every webhook delivery includes an X-Webhook-Signature header with the value sha256={hex_digest}. Always verify this signature before processing the payload to prevent spoofing.
import crypto from 'crypto';
export async function POST(request) {
const body = await request.text();
const signature = request.headers.get('X-Webhook-Signature');
const secret = process.env.IANEWS_WEBHOOK_SECRET;
const expected = 'sha256=' + crypto
.createHmac('sha256', secret)
.update(body)
.digest('hex');
const verified = crypto.timingSafeEqual(
Buffer.from(signature),
Buffer.from(expected)
);
if (!verified) {
return new Response('Invalid signature', { status: 401 });
}
const event = JSON.parse(body);
console.log(`Received ${event.event} for site ${event.site_id}`);
// Process the event asynchronously
return Response.json({ received: true });
}Always verify the HMAC signature before processing webhook payloads. Without verification, any third party could send forged events to your endpoint.
Delivery logs and retries
Each webhook has a Delivery Log accessible in Sites -- Webhooks -- select a webhook -- Delivery Log. Each entry shows the timestamp, event type, HTTP status, response time, and retry count.
If your server returns a non-2xx status code or does not respond within 30 seconds, IANews retries with exponential backoff: 1 second, 5 seconds, then 30 seconds. After 3 failed retries, the delivery is marked as failed. You can replay failed deliveries from the log.
Best practices
- Respond quickly -- Return
200immediately and process the event asynchronously to avoid timeouts. - Handle duplicates -- Use the
event_idfield to deduplicate, as retries may deliver the same event twice. - Monitor logs -- Persistent failures indicate endpoint misconfiguration or downtime.
- Rotate secrets -- If compromised, delete the webhook and create a new one with a fresh secret.
What's next?
- WordPress -- Publish directly to WordPress via the REST API
- Ghost CMS -- Publish to Ghost with newsletter integration
- NextJS Direct -- Write articles directly to PostgreSQL for your Next.js site