Skip to main content

​
Scouts by Yutori: Webhooks

Scouts webhooks are available as part of the Enhanced plan.
See pricing details.

​
Setup

  1. Go to the updates page of your Scout:
    https://scouts.yutori.com/<scout_id>     Example:
    https://scouts.yutori.com/9bfdd5b1-0e3d-4286-b5bf-9eebbd8c65d7
  2. Append /webhook to the URL:
    https://scouts.yutori.com/<scout_id>/webhook
You can also configure webhooks programmatically when creating scouts or browsing tasks via the API by passing a webhook_url field to the POST /v1/scouting or POST /v1/browsing endpoints. This will create a scout_webhook subscription for the calling user.

​
Webhook Formats

Scouts support two webhook formats:
  • Zapier-formatted (zapier_webhook)
  • Custom-formatted (scout_webhook)

​
Zapier Webhook Format

The zapier_webhook format uses a flattened structure for easier field mapping in Zapier workflows.

​
Example Request

POST https://hooks.zapier.com/hooks/catch/123456/abcdef/
Content-Type: application/json
User-Agent: Scout-Webhook/1.0
X-Scout-Event: scout.update

{
  "event_type": "scout_update",
  "scout_id": "scout-123",
  "scout_name": "Reddit Posts Monitor",
  "scout_query": "Posts on r/sanfrancisco about new offices opening in downtown sf",
  "update_id": "550e8400-e29b-41d4-a716-446655440000",
  "timestamp": "2024-08-05T15:30:45.123456Z",
  "status": "completed",
  "has_changes": true,
  "summary": "Found 3 new posts about office openings in downtown SF",
  "details_url": "https://scouts.yutori.com/scout-123",
  "report_content": "...",
  "change_status": "changes_detected",
  "formatted_timestamp": "2024-08-05 15:30:45 UTC"
}
In Zapier, create a new Zap using “Webhooks by Zapier” as the trigger. Set the trigger to Catch Hook. Route the webhook output into any action step (e.g., send email, Slack message). Map the webhook fields to the appropriate fields in your chosen action step. Scout Webhook Format (“Custom”) The scout_webhook format is a structured JSON format that provides nested data. Example Request POST https://your-webhook-endpoint.com/webhook Content-Type: application/json User-Agent: Scout-Webhook/1.0 X-Scout-Event: scout.update 
{
  "event_type": "scout_update",
  "scout": {
    "id": "scout-123",
    "display_name": "Reddit Posts Monitor",
    "query": "Posts on r/sanfrancisco about new offices opening in downtown sf"
  },
  "update": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "timestamp": "2024-08-05T15:30:45.123456Z",
    "status": "completed",
    "has_changes": true,
    "summary": "Found 3 new posts about office openings in downtown SF",
    "details_url": "https://scouts.yutori.com/scout-123",
    "report_content": "..."
  },
  "delivery": {
    "id": "550e8400-e29b-41d4-a716-446655440001",
    "attempt": 1,
    "timestamp": "2024-08-05T15:30:45.123456Z"
  }
}

​
Field Descriptions

FieldDescription
event_typeAlways "scout_update"
scout.idUnique identifier for the Scout
scout.display_nameHuman-readable name
scout.queryOriginal query/task description
update.idUnique identifier for this update
update.timestampISO 8601 timestamp when update was generated
update.statusTypically "completed"
update.has_changesBoolean indicating if new content was found
update.summaryBrief description of what was found
update.details_urlURL to view full results
update.report_contentRaw content of the update
delivery.idUnique identifier for this delivery attempt
delivery.attemptDelivery attempt number (starts at 1)
delivery.timestampTimestamp when webhook was sent

​
Webhook Delivery Details

​
Headers

All webhooks include: Content-Type: application/json User-Agent: Scout-Webhook/1.0 X-Scout-Event: scout.update Headers

​
Headers

All webhooks include these 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 (default timeout)

​
Error Handling

Scout will consider delivery failed if:
  • HTTP response status is not 2xx
  • Request times out (default 10 seconds)
  • Network error occurs
Failed deliveries are logged but not automatically retried.

​
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

​
Example Integration Code

​
Python (Flask)

from flask import Flask, request, jsonify

app = Flask(__name__)

@app.route('/webhook', methods=['POST'])
def handle_scout_webhook():
    payload = request.get_json()

    # Handle scout_webhook format
    if 'event' in payload and payload['event_type'] == 'scout_update':
        scout_name = payload['scout']['display_name']
        has_changes = payload['update']['has_changes']
        summary = payload['update']['summary']

        print(f"Scout '{scout_name}' update: {summary}")

    return jsonify({'status': 'received'}), 200

​
Node.js (Express)

const express = require('express');
const app = express();

app.use(express.json());

app.post('/webhook', (req, res) => {
    const payload = req.body;

    // Handle scout_webhook format
    if (payload.event === 'scout_update') {
        const scoutName = payload.scout.display_name;
        const hasChanges = payload.update.has_changes;
        const summary = payload.update.summary;

        console.log(`Scout '${scoutName}' update: ${summary}`);
    }
    res.status(200).json({ status: 'received' });
});

app.listen(3000, () => {
    console.log('Webhook server listening on port 3000');
});