Webhooks

AgentaOS signs every webhook it sends to your server. Verify the signature before you act on the body. The events and their payloads are in the event reference.

Signature verification

Every delivery includes an X-AgentaOS-Signature header:

X-AgentaOS-Signature: t=1770379200,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd

Part	Meaning
`t`	Unix timestamp (seconds) when the signature was generated.
`v1`	HMAC-SHA256 hex digest of `{t}.{raw request body}`, keyed with your webhook signing secret.

Get your signing secret (whsec_...) in Settings → Developers → Webhooks: click Reveal signing secret. The secret stays the same when you change the URL. If it is exposed, click Rotate secret on the same screen.

SDK (Node.js)
Manual (any language)

import { AgentaOS, WebhookVerificationError } from '@agentaos/pay';
import express from 'express';

const agentaos = new AgentaOS(process.env.AGENTAOS_API_KEY!);
const app = express();

// Use express.raw(): verification needs the exact raw body bytes.
app.post('/webhooks', express.raw({ type: 'application/json' }), (req, res) => {
  try {
    const event = agentaos.webhooks.verify(
      req.body,
      req.headers['x-agentaos-signature'] as string,
      process.env.AGENTAOS_WEBHOOK_SECRET!,
    );

    if (event.type === 'checkout.session.completed') {
      fulfillOrder(event.data.sessionId); // your own code
    }

    res.sendStatus(200);
  } catch (err) {
    if (err instanceof WebhookVerificationError) {
      res.status(400).send('Invalid signature');
      return;
    }
    res.status(500).send('Webhook processing failed');
  }
});

app.listen(3000);

import hmac, hashlib, time

def verify_webhook(raw_body: str, signature: str, secret: str) -> bool:
    parts = dict(p.split('=', 1) for p in signature.split(','))
    timestamp = int(parts['t'])

    # Reject a signature older than 5 minutes, or from the future
    age = int(time.time()) - timestamp
    if age < 0 or age > 300:
        return False

    expected = hmac.new(
        secret.encode(),
        f"{timestamp}.{raw_body}".encode(),
        hashlib.sha256,
    ).hexdigest()

    return hmac.compare_digest(expected, parts['v1'])

Verify against the raw request body bytes, before any JSON parsing or re-serialization. Re-stringifying a parsed object can reorder keys or change whitespace and silently break the signature check.

Delivery

Timeouts, attempts, redirects and refused addresses are in Delivery and retries. Return 2xx quickly and do slow work (emails, fulfillment) after you respond. A slow handler can time out and cause a retry.

SDK

CLI

API Reference

Signature verification

Delivery

​Signature verification

​Delivery

Signature verification

Delivery