Webhooks & Events

Webhooks push real-time notifications when important events occur so your systems can react instantly without polling the API.

Supported Events

Creating a Subscription

1. Go to Workspace Settings → Integrations → Webhooks.
2. Click Create Subscription.
3. Provide the public HTTPS endpoint that will receive events.
4. Select the events to subscribe to.
5. Copy the signing secret (displayed once) and store it securely.

You can also manage subscriptions via the API:

POST /webhooks
{
  "url": "https://hooks.yourdomain.com/altyaa",
  "events": ["post.published", "review.created"]
}

Delivery Behavior

• Events are delivered as JSON via POST requests.
• Retries use exponential backoff: 1 min, 5 min, 15 min, 1 hr (up to 24 hours total).
• After repeated failures the subscription is paused and you receive an email notification.

Verifying Signatures

Each payload includes headers to verify authenticity:

X-Altyaa-Signature: t=1731523200,v1=hash

To verify:

1. Concatenate the timestamp, period (.), and raw request body.
2. Compute an HMAC SHA-256 hash with your webhook secret.
3. Compare the computed hash to the v1 value.
4. Reject requests where the timestamp differs by more than 5 minutes to prevent replay attacks.

Example (TypeScript):

import crypto from 'node:crypto';

export function verifySignature({ body, header, secret }: {
  body: string;
  header: string;
  secret: string;
}) {
  const [timestampPart, hashPart] = header.split(',');
  const timestamp = timestampPart.split('=')[1];
  const providedHash = hashPart.split('=')[1];

  const payload = `${timestamp}.${body}`;
  const expectedHash = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');

  return crypto.timingSafeEqual(Buffer.from(providedHash), Buffer.from(expectedHash));
}

Processing Payloads

Payloads share a common envelope:

{
  "id": "evt_01hdw6q2t5z9",
  "type": "post.published",
  "createdAt": "2025-10-14T10:21:00.000Z",
  "data": {
    "workspaceId": "wksp_123",
    "postId": "post_456",
    "publishedAt": "2025-10-14T10:20:00.000Z"
  }
}

Use the id to deduplicate events—retry deliveries reuse the same ID.

Securing Your Endpoint

• Serve webhooks over HTTPS only.
• Validate the signature before processing the payload.
• Return a 2xx response within 10 seconds. For longer work, enqueue a background job and acknowledge immediately.
• Use allowlists or secret URLs combined with the signing secret for defense in depth.

Continue to Rate Limits & Quotas to understand delivery expectations, or dive into Scheduling & Data Model to see how posts transition through lifecycle events.