Webhooks & Callbacks

Overview

Instead of polling for results, you can configure webhooks to receive automatic notifications when your flows complete. When you provide a callback configuration in your request, Edges will send a POST request to your specified URL with the results.

For action callbacks (outside of Flows), refer to the Managing Callbacks documentation in the main Edges docs.

Setting up callbacks

Include a callback object in your flow run request:

{
  "inputs": [...],
  "callback": {
    "url": "https://your-app.com/webhook",
    "headers": {
      "Authorization": "Bearer your-secret-token"
    },
    "on": "all"
  }
}

Field	Type	Required	Description
`url`	string	Yes	The URL where Edges will send webhook notifications
`headers`	object	No	Custom headers to include in the webhook request (e.g., for authentication)
`on`	string	No	When to receive callbacks: `"all"` (default) sends callbacks as outputs are generated, `"final"` sends a single callback when the flow completes or errors

Always include an authentication header in your callback configuration to secure your webhook endpoint and verify that requests are coming from Edges.

Webhook payload

When a flow completes (or reaches milestones), Edges sends this payload:

FlowWebhookPayload = {
  flow_run: {
    flow_run_uid: string    // Unique identifier for the flow run
    step_uid: string        // The step that triggered this callback
    status: string          // Current status of the flow run
  }
  error?: any               // Error details if the flow failed
  results_count?: number    // Number of results returned
  results?: any[]           // Array of result objects
}

Example payload:

{
  "flow_run": {
    "flow_run_uid": "550e8400-e29b-41d4-a716-446655440000",
    "step_uid": "linkedin-extract-people",
    "status": "SUCCEEDED"
  },
  "results_count": 25,
  "results": [
    {
      "linkedin_profile_url": "https://linkedin.com/in/example",
      "first_name": "John",
      "last_name": "Doe",
      "headline": "Software Engineer at Example Corp"
    }
    // ... more results
  ]
}

Status values

The status field in the webhook payload can have the following values:

Status	Description
`CREATED`	Flow run has been created
`QUEUED`	Flow run is queued for execution
`RUNNING`	Flow run is currently executing
`SUCCEEDED`	Flow run completed successfully
`FAILED`	Flow run failed
`PARTIAL_SUCCEEDED`	Flow run partially succeeded (some items failed)

Handling webhooks

Here’s an example of how to handle flow webhook payloads in your application:

from flask import Flask, request, jsonify

app = Flask(__name__)

@app.route('/webhook', methods=['POST'])
def handle_webhook():
    # Verify the request (check your auth header)
    auth_header = request.headers.get('Authorization')
    if auth_header != 'Bearer your-secret-token':
        return jsonify({'error': 'Unauthorized'}), 401
    
    payload = request.json
    flow_run = payload['flow_run']
    
    print(f"Flow {flow_run['flow_run_uid']} - Step {flow_run['step_uid']}")
    print(f"Status: {flow_run['status']}")
    
    if flow_run['status'] == 'FAILED':
        print(f"Error: {payload.get('error')}")
    elif payload.get('results'):
        print(f"Received {payload.get('results_count', len(payload['results']))} results")
        for result in payload['results']:
            # Process each result
            print(f"Result: {result}")
    
    return jsonify({'status': 'received'}), 200

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

app.use(express.json());

app.post('/webhook', (req, res) => {
  // Verify the request (check your auth header)
  const authHeader = req.headers['authorization'];
  if (authHeader !== 'Bearer your-secret-token') {
    return res.status(401).json({ error: 'Unauthorized' });
  }

  const payload = req.body;
  const { flow_run_uid, step_uid, status } = payload.flow_run;

  console.log(`Flow ${flow_run_uid} - Step ${step_uid}`);
  console.log(`Status: ${status}`);

  if (status === 'FAILED') {
    console.log('Error:', payload.error);
  } else if (payload.results) {
    console.log(`Received ${payload.results_count || payload.results.length} results`);
    payload.results.forEach(result => {
      // Process each result
      console.log('Result:', result);
    });
  }

  res.status(200).json({ status: 'received' });
});

app.listen(3000);

Best practices

Secure your webhook endpoint

Always use HTTPS for your webhook URL and include an authentication header in your callback configuration. Verify this header in your webhook handler to ensure requests are coming from Edges.

Respond quickly

Your webhook endpoint should respond with a 2xx status code within a few seconds. If you need to do heavy processing, acknowledge the webhook first and process asynchronously.

Handle retries gracefully

Edges may retry failed webhook deliveries. Make your webhook handler idempotent by checking if you’ve already processed a given flow_run_uid.

Handle errors

Always check the status field and handle error cases. If status is FAILED, check the error field for details about what went wrong.

Webhook delivery is best-effort. For critical workflows, we recommend also polling the Get Flow Run endpoint as a fallback to ensure you don’t miss any results.

API documentation

Runs & Schedules

Flows Presets

Single Actions

Overview

Setting up callbacks

Webhook payload

Status values

Handling webhooks

Best practices

​Overview

​Setting up callbacks

​Webhook payload

​Status values

​Handling webhooks

​Best practices

Overview

Setting up callbacks

Webhook payload

Status values

Handling webhooks

Best practices