Skip to main content
You can provide a webhook URL when using any of the create endpoints: Create Scout, Create Research, or Create Browsing. The scout_webhook format is a structured JSON format that provides nested data. If you want Slack-compatible payloads, provide a Slack incoming webhook URL and set webhook_format to slack when creating or updating the scout. Slack payloads use Block Kit formatting.

Example Request

Below is an example of the HTTP request that a Scout sends to your webhook endpoint.

Slack Incoming Webhook Payload (Example)

Field Descriptions

Webhook Delivery Details

Headers

All webhook requests include the following headers:
  • Content-Type: application/json
  • User-Agent: Scout-Webhook/1.0
  • X-Scout-Event: scout.update

Response Expectations

Your webhook endpoint should:
  • Respond with HTTP status 200-299 for successful receipt
  • Process the webhook asynchronously if needed
  • Respond within 10 seconds per delivery attempt

Error Handling

Scout will consider delivery failed if:
  • HTTP response status is not 2xx
  • Request times out (default 10 seconds)
  • Network error occurs
Retryable failures (timeouts, network errors, and HTTP 408, 409, 425, 429, 500, 502, 503, and 504) are retried up to 3 total attempts with short exponential backoff. With the default 10-second timeout, timeout-based failures complete in roughly 30-35 seconds. If all attempts fail, the Scout finding remains available in Yutori, but webhook delivery is not queued for later redelivery.

Security Considerations

  • Use HTTPS URLs for production webhooks
  • HTTP URLs are only allowed for localhost/127.0.0.1 (testing)
  • Validate webhook payload structure in your endpoint
  • Consider implementing webhook signature verification for additional security

Smoke Test

You can send a test webhook from the API using your API key:

Example Integration Code

Python (Flask)

Node.js (Express)