FansquareAPI reference
Open the app

Receiving webhooks

AI control requested

EVENTconversation.ai_control_requested

A user of the Fansquare app asked to relaunch (relaunch) or to stop (stop) your AI on a conversation. Handle the request, then acknowledge its request_id with POST /v1/accounts/{account_id}/ai-requests/ack.

Only the Fansquare app emits this event, never the AI-lock endpoints of this API. A conversation holds at most one pending request: asking again replaces its intent and emits again, with the same request_id. A request cancelled in the app before you acknowledge it emits nothing and leaves the pending list. That list (GET /v1/accounts/{account_id}/ai-requests) is the source of truth, the webhook only signals it sooner. The app accepts requests only while an active endpoint of the agency subscribes to this event for the creator.

created_at is the time of the request.

Payload
{
  "id": "0199c7a2-5d4e-7b3a-9f1e-2c8d6b4a1e07",
  "type": "conversation.ai_control_requested",
  "created_at": "2026-10-12T21:14:00.000Z",
  "api_version": "2026-07-06",
  "data": {
    "account_id": "c851d9d6-b90b-4958-aed2-2fdaa2fe21a3",
    "fan_id": "a6df8022-e509-4575-ad28-e29c2d1d42dc",
    "intent": "relaunch",
    "request_id": "0cbdfaac-d0e9-419e-a7b9-b438a95c3862"
  }
}

Delivery headers

  • Fansquare-Signaturestringrequired

    Signature of the delivery: v1= followed by the hexadecimal HMAC-SHA256 of {Fansquare-Signature-Timestamp}.{raw body}, keyed with the signing secret of the endpoint. Compute it over the raw body, before any JSON parsing, and compare in constant time.

  • Fansquare-Signature-Timestampintegerrequired

    Unix time, in seconds, at which this attempt was signed. Each attempt is signed again. Reject a delivery whose timestamp is more than 5 minutes away from your clock: it blocks replays of an intercepted delivery.

  • Fansquare-Event-Typestringrequired

    Event type, the type of the body.

  • Fansquare-Event-Idstringrequired

    Event id, the id of the body. The same across automatic retries and replays: deduplicate on it.

    format uuid
  • Fansquare-Delivery-Idstringrequired

    Id of this delivery of the event to this endpoint. The same across the automatic retries (10 seconds, 1 minute, then 5 minutes after a failed attempt), new on a replay. Any response other than a 2xx within 10 seconds, redirects included, is a failed attempt; after the last one the delivery is listed by GET /v1/webhooks/{endpoint_id}/failures.

    format uuid
  • User-Agentstringrequired

    Always Offmy-Webhooks/1.0.

Delivery body

  • idstringrequired

    Event id. The same for every endpoint that receives the event, and across automatic retries and replays: deduplicate on it. Also sent as the Fansquare-Event-Id header.

    format uuid
  • type"conversation.ai_control_requested"required

    Event type. Also sent as the Fansquare-Event-Type header.

  • created_atstringrequired

    When the fact occurred (ISO 8601, UTC), not when this delivery was sent: a retry or a replay carries the original value. The description of each event says which instant it is.

    format date-time
  • api_versionstringrequired

    Version the payload is rendered in: the release date of the version pinned on the endpoint at its creation (the api_version of the endpoint), for example 2026-07-06.

  • dataobjectrequired
Payload
{
  "id": "0199c7a2-5d4e-7b3a-9f1e-2c8d6b4a1e07",
  "type": "conversation.ai_control_requested",
  "created_at": "2026-10-12T21:14:00.000Z",
  "api_version": "2026-07-06",
  "data": {
    "account_id": "c851d9d6-b90b-4958-aed2-2fdaa2fe21a3",
    "fan_id": "a6df8022-e509-4575-ad28-e29c2d1d42dc",
    "intent": "relaunch",
    "request_id": "0cbdfaac-d0e9-419e-a7b9-b438a95c3862"
  }
}