Webhooks: push agent events to your systems

Outbound webhooks push agent events to your URLs. Every delivery is signed with HMAC-SHA256 so you can verify it came from us.

Webhooks let your own systems react to what your Fine Structure agents do. When an event happens, we send an HTTP POST with a JSON body to the URLs you configure. You manage subscriptions on the Agent Webhooks page at finestructure.ai/agent-webhooks, where each subscription gets its own signing secret.

Event | Sent when

conversation.created | A new agent conversation starts on any channel.

message.created | A user or assistant message is added to a conversation.

message.completed | An assistant reply finishes successfully.

ping | You press the test button on a subscription.

Delivery headers

• X-FSE2-Signature: sha256=<HMAC-SHA256 hex of the raw request body, keyed with your subscription secret>.
• X-FSE2-Event: the event type, for example message.created.
• X-FSE2-Event-Id: stable id of the event, use it to deduplicate.
• X-FSE2-Delivery: unique id of this delivery attempt.
• X-FSE2-Timestamp: when the delivery was sent.

Always verify the signature before trusting a payload. Compute HMAC-SHA256 over the exact raw body bytes with your subscription secret, hex-encode it, prefix it with sha256=, and compare against the header using a constant-time comparison.

import crypto from "crypto"

function verify(rawBody, header, secret) {
  const expected = "sha256=" + crypto
    .createHmac("sha256", secret)
    .update(rawBody)
    .digest("hex")
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(header || "")
  )
}

import hashlib, hmac

def verify(raw_body: bytes, header: str, secret: str) -> bool:
    expected = "sha256=" + hmac.new(
        secret.encode(), raw_body, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, header or "")

Delivery behavior

• Respond with any 2xx status within a few seconds to acknowledge.
• Failed deliveries retry with exponential backoff, up to 6 attempts, then move to a dead-letter log you can inspect.
• Deliveries can arrive out of order; use X-FSE2-Event-Id and the timestamp to order and deduplicate.
• Rotate the subscription secret at any time from the Agent Webhooks page.

Keep the raw body raw: Signature verification must run on the exact bytes we sent. If your framework parses JSON before you verify, re-serialization can change the bytes and the signature will not match. Read the raw body first, verify, then parse.