Skip to main content

​
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"
    }
  }
}
FieldTypeRequiredDescription
urlstringYesThe URL where Edges will send webhook notifications
headersobjectNoCustom headers to include in the webhook request (e.g., for authentication)
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:
StatusDescription
CREATEDFlow run has been created
QUEUEDFlow run is queued for execution
RUNNINGFlow run is currently executing
SUCCEEDEDFlow run completed successfully
FAILEDFlow run failed
PARTIAL_SUCCEEDEDFlow 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

​
Best practices

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.
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.
Edges may retry failed webhook deliveries. Make your webhook handler idempotent by checking if you’ve already processed a given flow_run_uid.
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.