Webhook HTTP integration

This page calls the full Hook URL from an Agent's details page using its saved configuration. For API key authentication, create a single-Agent conversation key using the AIP API quickstart. The two methods use different URLs and credentials.

Prepare the invocation URL

Ensure the Agent is enabled and test the same task in debugging first. These examples perform real execution.

Send the first message

curl --fail-with-body "$AIP_HOOK_URL" \
  -H 'Content-Type: application/json' \
  --data '{
    "action": "created",
    "payload": {
      "session_id": "requirements-demo-001",
      "request_id": "message-001",
      "prompt": "Organize this requirement: support staff can enter an order number to check its status.",
      "context": {"source": "requirements-form"}
    }
  }'

Reuse session_id within a conversation. Use a new request_id for each new message; for a retry, retain the original identifier and request content. These identifiers are examples; generate distinct identifiers for separate conversations and messages in your application.

After acceptance, read execution events. Successful submission does not mean the task is complete.

Receive streamed replies

curl -N --fail-with-body "$AIP_HOOK_URL" \
  -H 'Content-Type: application/json' \
  --data '{
    "action": "sse",
    "payload": {
      "session_id": "requirements-demo-001",
      "after_event_id": 0
    }
  }'

Use the session identifier from the response. Save the last received event sequence, resume from it after disconnection, and deduplicate by sequence.

Continue the conversation

curl --fail-with-body "$AIP_HOOK_URL" \
  -H 'Content-Type: application/json' \
  --data '{
    "action": "prompted",
    "payload": {
      "session_id": "requirements-demo-001",
      "request_id": "message-002",
      "signal": "continue",
      "prompt": "Sort the open questions by priority."
    }
  }'

Stop generation

curl --fail-with-body "$AIP_HOOK_URL" \
  -H 'Content-Type: application/json' \
  --data '{
    "action": "prompted",
    "payload": {
      "session_id": "requirements-demo-001",
      "signal": "stop"
    }
  }'

Closing SSE only stops event reception. To stop execution, send the stop request above and continue observing the outcome.

Request fields

Your service owns its message entry point, user validation, and session mapping. Assign distinct session identifiers to different customers.