API REFERENCE

Slack webhook

On this page

POST/api/content-agent/{platform}

Webhook endpoint for the Recoup Content Agent Slack bot. Receives @mention events from Slack and triggers content generation for the mentioned artist. The bot parses the mention text for <artist_account_id> [template] [batch=N] [lipsync], validates the artist, calls POST /api/content/create, and starts a background polling task that reports results back to the Slack thread.

For Slack, also handles url_verification challenges during app setup.

Slack supplies X-Slack-Signature and X-Slack-Request-Timestamp. Setup verification checks the exact raw body with the configured Content Agent app signing secret and accepts timestamps within five minutes of the server clock. A valid url_verification request returns the JSON challenge; missing or invalid setup signatures, an out-of-window timestamp, or an unavailable app signing secret return 401 with plain-text Unauthorized. Ordinary events continue through the existing Slack adapter.

Authentication

See the authentication guide for API key and account access requirements.

Request

cURL

curl --request POST \
  --url 'https://api.recoupable.dev/api/content-agent/YOUR_PLATFORM' \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'X-Slack-Signature: YOUR_VALUE' \
  --header 'X-Slack-Request-Timestamp: YOUR_VALUE' \
  --header 'Content-Type: application/json' \
  --data '{}'

Replace the YOUR_ placeholders with your values. Required query parameters are included; optional parameters are listed below.

Try it

Fill in the fields, send the request from your browser, and read the live response. The curl below updates as you type.

API keyx-api-key header

Kept in this browser tab only and cleared when it closes.

platformpath · stringrequired

X-Slack-Signatureheader · stringrequired

X-Slack-Request-Timestampheader · stringrequired

Request bodyapplication/json

cURL for this request

curl --request POST \
  --url 'https://api.recoupable.dev/api/content-agent/{platform}' \
  --header 'Content-Type: application/json' \
  --data '{}'

Parameters

Path parameters

platformstring · enumrequired

Chat platform identifier. Currently supports slack.

Values: "slack"

Header parameters

X-Slack-Signaturestringrequired

Slack-generated signature for this request. Recoup verifies it with the Content Agent app signing secret; send the computed signature, never the signing secret itself.

X-Slack-Request-Timestampstringrequired

Slack-generated Unix timestamp in seconds. Setup verification rejects timestamps more than five minutes before or after the server clock.

Request body required

Slack Events API payload (app_mention event or url_verification challenge)

application/json

object

Responses

200A verified setup challenge is echoed as JSON. Ordinary JSON event callbacks receive the Slack adapter's plain-text ok acknowledgement; this acknowledges receipt while content generation continues separately.

application/json

challengestringrequired

Echo of the verified Slack setup challenge.

Verified setup challenge

verifiedSetup

{
  "challenge": "example-challenge"
}

text/plain

string

200 example

ok

401Slack signature verification failed. Setup challenges use plain-text Unauthorized for missing or invalid signatures, timestamps outside the five-minute window, or an unavailable configured signing secret. The existing adapter handles ordinary event authentication and currently uses plain-text Invalid signature.

text/plain

string

Setup signature rejected

setupChallenge

Unauthorized

Event signature rejected by the adapter

ordinaryEvent

Invalid signature

404Unknown platform

No response body schema is specified.

Full specification

Download the OpenAPI file for complete schemas, constraints, and examples.

Download content.json

View operation source

json

{
  "operationId": "postContentAgentByPlatform",
  "description": "Webhook endpoint for the Recoup Content Agent Slack bot. Receives @mention events from Slack and triggers content generation for the mentioned artist. The bot parses the mention text for `<artist_account_id> [template] [batch=N] [lipsync]`, validates the artist, calls POST /api/content/create, and starts a background polling task that reports results back to the Slack thread.\n\nFor Slack, also handles `url_verification` challenges during app setup.\n\nSlack supplies `X-Slack-Signature` and `X-Slack-Request-Timestamp`. Setup verification checks the exact raw body with the configured Content Agent app signing secret and accepts timestamps within five minutes of the server clock. A valid `url_verification` request returns the JSON challenge; missing or invalid setup signatures, an out-of-window timestamp, or an unavailable app signing secret return `401` with plain-text `Unauthorized`. Ordinary events continue through the existing Slack adapter.",
  "parameters": [
    {
      "name": "platform",
      "in": "path",
      "description": "Chat platform identifier. Currently supports `slack`.",
      "required": true,
      "schema": {
        "type": "string",
        "enum": [
          "slack"
        ]
      }
    },
    {
      "name": "X-Slack-Signature",
      "in": "header",
      "required": true,
      "description": "Slack-generated signature for this request. Recoup verifies it with the Content Agent app signing secret; send the computed signature, never the signing secret itself.",
      "schema": {
        "type": "string"
      }
    },
    {
      "name": "X-Slack-Request-Timestamp",
      "in": "header",
      "required": true,
      "description": "Slack-generated Unix timestamp in seconds. Setup verification rejects timestamps more than five minutes before or after the server clock.",
      "schema": {
        "type": "string"
      }
    }
  ],
  "requestBody": {
    "description": "Slack Events API payload (app_mention event or url_verification challenge)",
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "description": "Slack Events API envelope — the shape depends on the event type"
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "A verified setup challenge is echoed as JSON. Ordinary JSON event callbacks receive the Slack adapter's plain-text ok acknowledgement; this acknowledges receipt while content generation continues separately.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "challenge": {
                "type": "string",
                "description": "Echo of the verified Slack setup challenge."
              }
            },
            "required": [
              "challenge"
            ]
          },
          "examples": {
            "verifiedSetup": {
              "summary": "Verified setup challenge",
              "value": {
                "challenge": "example-challenge"
              }
            }
          }
        },
        "text/plain": {
          "schema": {
            "type": "string"
          },
          "example": "ok"
        }
      }
    },
    "401": {
      "description": "Slack signature verification failed. Setup challenges use plain-text Unauthorized for missing or invalid signatures, timestamps outside the five-minute window, or an unavailable configured signing secret. The existing adapter handles ordinary event authentication and currently uses plain-text Invalid signature.",
      "content": {
        "text/plain": {
          "schema": {
            "type": "string"
          },
          "examples": {
            "setupChallenge": {
              "summary": "Setup signature rejected",
              "value": "Unauthorized"
            },
            "ordinaryEvent": {
              "summary": "Event signature rejected by the adapter",
              "value": "Invalid signature"
            }
          }
        }
      }
    },
    "404": {
      "description": "Unknown platform"
    }
  }
}

Get started with Recoup.

Try Our Platform

Build Your Platform