Guides
Webhooks
Receive real-time event notifications from Aether via HTTP callbacks.
Webhooks deliver signed JSON payloads to your server when events occur — posts publish, profiles connect, inbox messages arrive, and more.
Creating a webhook
curl -X POST https://api.aetherhq.dev/v1/webhooks \
-H "Authorization: Bearer $AETHER_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://your-server.com/webhooks/aether",
"events": ["post.published", "post.failed"],
"description": "Production webhook"
}'The response includes secret — shown exactly once. Store it securely.
Verifying signatures
Every request includes X-Aether-Signature: sha256=<hex-digest>.
Algorithm: HMAC-SHA256(key=plainSecret, message=rawRequestBody)
import crypto from "node:crypto";
function verifyAetherWebhook(
rawBody: string,
signature: string,
secret: string,
): boolean {
const expected = `sha256=${crypto
.createHmac("sha256", secret)
.update(rawBody)
.digest("hex")}`;
return crypto.timingSafeEqual(
Buffer.from(signature),
Buffer.from(expected),
);
}Verify the raw body before JSON parsing.
Request headers
| Header | Value |
|---|---|
Content-Type | application/json |
X-Aether-Signature | sha256=<hex> |
X-Aether-Event | Event type |
X-Aether-Delivery | Unique delivery ID |
User-Agent | Aether-Webhooks/1.0 |
Event reference
Post lifecycle
| Event | Description |
|---|---|
post.published | Post published to all target profiles |
post.failed | All target profiles failed |
post.scheduled | Post scheduled for future publish |
post.cancelled | Scheduled post cancelled |
post.platform.publishing | Single platform publish started |
post.platform.published | Single platform publish succeeded |
post.platform.failed | Single platform publish failed |
Inbox
| Event | Description |
|---|---|
inbox.message_received | New DM or inbox item |
inbox.comment_received | New comment |
Automations
| Event | Description |
|---|---|
automation.triggered | Comment-to-DM automation ran |
Profiles
| Event | Description |
|---|---|
profile.connected | Account connected via OAuth |
profile.disconnected | Account disconnected |
profile.token_expired | Token refresh failed |
profile.error | Profile entered error state |
Connect links
| Event | Description |
|---|---|
connect_link.used | Connect link consumed |
connect_link.expired | Connect link expired unused |
Retries
Non-2xx responses trigger up to 5 retries with exponential backoff (~1s, 2s, 4s, 8s). Return 200 quickly and process asynchronously.
Delivery logs
curl https://api.aetherhq.dev/v1/webhooks/{webhookId}/deliveries \
-H "Authorization: Bearer $AETHER_API_KEY"See Webhooks API.