Webhooks

Instead of polling, subscribe to events and Ardent will POST them to your URL as they happen. Create and manage webhooks in your developer dashboard.

Events

Some events are yours alone

Most topics above are broadcast: the content is already public, so every subscription listening for the topic receives every event.

social.follower.gained and social.mention.created are scoped. They are delivered only to subscriptions owned by the account the event is about. You will never receive a follower event for somebody else's profile.

That distinction is not cosmetic. Both handles in a follower event belong to public profiles, but the edge between them is not public, and an endpoint collecting broadcast edges would reconstruct the whole social graph. The same reasoning is why the read API has no endpoint for follows, connections or group members at all.

social.post.published is broadcast, because it fires only for a post whose author chose a public audience, which anybody can already read at its permalink. A post limited to followers, to connections, or to a group never produces a webhook, and a mention inside such a post does not either.

Payloads contain public fields only: never donor, signer, organizer, attendee, candidate, reviewer, or claimant personal data.

This is deliberate for the job events. application.received tells you a posting got an application and how many it now has; it does not tell you who applied. application.status_changed gives you the coarse pipeline status only. No name, email, phone, CV, cover letter, screening answer, or candidate id ever crosses a webhook boundary, because a job seeker's identity leaking to a third-party endpoint could cost them their current job. Use the employer dashboard or the authenticated API for applicant detail.

Delivery

Each delivery is a POST with a JSON body and these headers:

Content-Type: application/json
X-Ardent-Event: petition.signed
X-Ardent-Signature: t=1718900000,v1=9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08

Respond with any 2xx to acknowledge. Non-2xx (or a timeout) is retried with exponential backoff for up to 8 attempts, after which the delivery is dead-lettered. You can replay it from the dashboard. You can also send a test event to any endpoint.

Verifying the signature

v1 is the hex HMAC-SHA256 of <t>.<raw-request-body>, keyed by your subscription's signing secret (shown once when you create or rotate the webhook). Always verify before trusting a payload, and reject timestamps outside a few minutes to prevent replays.

// Node - use the RAW request body, not a re-serialized object.
import crypto from 'node:crypto'

function verify(secret, signatureHeader, rawBody) {
  const parts = Object.fromEntries(signatureHeader.split(',').map((p) => p.split('=')))
  const expected = crypto.createHmac('sha256', secret).update(`${parts.t}.${rawBody}`).digest('hex')
  const ok = crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1))
  const fresh = Math.abs(Date.now() / 1000 - Number(parts.t)) < 300
  return ok && fresh
}

<?php
function ardent_verify(string $secret, string $header, string $rawBody): bool {
  parse_str(str_replace(',', '&', $header), $p);
  $expected = hash_hmac('sha256', $p['t'] . '.' . $rawBody, $secret);
  return hash_equals($expected, $p['v1'] ?? '') && abs(time() - (int) $p['t']) < 300;
}

Security notes

• Only HTTPS endpoints are accepted, and Ardent will not deliver to private, loopback, or link-local addresses.
• Treat the signing secret like a password. If it leaks, rotate it from the dashboard.
• Delivery is at-least-once. Handle the occasional duplicate idempotently.

Last updated: 24 August 2026