Managing Callbacks

What are Callbacks?

Callbacks are the way Edges delivers results for async and schedule execution modes. Instead of waiting for the entire operation to complete, you receive results progressively as they become available.

When to use callbacks: Choose async or schedule mode when you need to process large datasets, want to consume data in parallel, or need to handle long-running operations without timeouts.

Callbacks are only useful if you can trust that all of them are received and processed.
To ensure you never miss any data, see Why Managing Callback History Matters.

Quick Start

1. Set up your webhook endpoint

Create an HTTPS endpoint that can receive POST requests with JSON payloads.

2. Configure your action call

Include a callback parameter with your webhook URL:

{
  "inputs": [...],
  "callback": {
    "url": "https://yourdomain.com/webhook",
    "headers": {
      "Authorization": "Bearer your_token"
    }
  }
}

3. Handle incoming callbacks

Process the JSON payloads as they arrive. Each callback contains results and metadata. For detailed setup and management, see the sections below.

Understanding Async and Schedule Modes

async and schedule execution modes are both async modes: the results are not sent immediately in the response payload but delivered during execution via callbacks.

schedule is built on top of async and only adds ways to postpone and schedule calls. Both modes share the same callback delivery mechanism. For a detailed comparison and guidance on when to use each mode, see When to use live, async or schedule modes..

Setting Up Callbacks

Every action call in async/schedule mode requires a callback parameter:

url

string

Your webhook URL that will receive the callback data. Must be HTTPS.

headers

array

Optional headers for authentication or custom metadata (API keys, etc.).

Please refer to each async/schedule action in the API Reference for specific details.

Callback Structure

All callbacks follow the same consistent format:

Callback Delivery: Both async and schedule modes deliver results via the callback URL provided in your request.Consistent Format: All execution modes use the same action logic, so inputs and results are identical regardless of mode.Error Handling: Errors follow the standard API error format.

async callback format

{
  "run": {
    "run_uid": "string",
    "batch_uid": "string",
    "status": "CREATED" || "INVALID" || "QUEUED" || "SCHEDULED" || "BLOCKED" || "STOPPED" || "RUNNING" || "FAILED" || "PARTIAL_SUCCEEDED" || "SUCCEEDED",
  },
  "input": {} || null,
  "custom_data": {} || null,
  "error": {} || null,
  "results": [] || null
}

To track or tag your inputs, you can attach any custom metadata to each input via the custom_data field. It is especially useful in async and schedule modes to help you get context on the results. This applies even when running with multiple inputs: each input will produce one or more callbacks, each carrying its own custom_data.This object is then injected as-is at the root of every callback, allowing you to correlate each result with your own data or internal references.

Callback Payload Fields

run

object

Execution context containing run_uid (unique to the entire run), batch_uid (unique to this batch), and status (current execution state).

input

object | null

The processed input data that was used for this batch (cleaned and validated by our engine).

custom_data

object | null

Your custom data passed via inputs.custom_data. Available at the root level for easy access.

error

object | null

Error details if this batch failed. Follows the standard API error format.

results

array | null

The actual results for this batch (null if there was an error). Format matches the specific action’s output.

Using `custom_data` to Track Inputs

One of the most powerful features of callbacks is the ability to attach custom metadata to each input using the custom_data object. This data is sent back in every callback, allowing you to correlate results with your internal systems.

1. Add `custom_data` to your inputs

When calling an action in async or schedule mode, include a custom_data field for each input.

{
  "inputs": [
    {
      "linkedin_profile_url": "https://www.linkedin.com/in/elisa-morgera-88b76b95/",
      "custom_data": {
        "internal_id": "12345",
        "type": "lead"
      }
    },
    {
      "linkedin_profile_url": "https://www.linkedin.com/in/astrid-puentes-ria%C3%B1o-83658a14/",
      "custom_data": {
        "internal_id": "671",
        "type": "lead"
      }
    }
  ],
  "callback": {
    "url": "https://yourdomain.com/webhook",
    "headers": {
      "Authorization": "Bearer your_token"
    }
  }
}

2. Receive `custom_data` in each callback

Each callback will include the same custom_data at the root level.
Example for the first input:

{
  "run": { "run_uid": "...", "batch_uid": "...", "status": "RUNNING" },
  "input": {
    "linkedin_profile_url": "https://www.linkedin.com/in/elisa-morgera-88b76b95/"
  },
  "custom_data": {
    "internal_id": "12345",
    "type": "lead"
  },
  "results": [ { "linkedin_profile_id": "...", "full_name": "Elisa Morgera" } ]
}

And for the second input:

{
  "run": { "run_uid": "...", "batch_uid": "...", "status": "RUNNING" },
  "input": {
    "linkedin_profile_url": "https://www.linkedin.com/in/astrid-puentes-ria%C3%B1o-83658a14/"
  },
  "custom_data": {
    "internal_id": "671",
    "type": "lead"
  },
  "results": [ { "linkedin_profile_id": "...", "full_name": "Astrid Puentes Riaño" } ]
}

3. Match and track on your side

You can now correlate each callback to internal data using the custom_data fields.
This makes it easy to process results in your own system — even with multiple inputs and parallel callbacks.

How Callbacks Work

Understanding how callbacks are processed and delivered helps you build robust integrations.

Parallel Processing & Pagination

Async actions are designed to scale efficiently by processing multiple pages concurrently:

Improved performance: Pages are processed in parallel
Manageable payloads: Each page generates a separate callback
Faster time-to-first-result: Start consuming data immediately

Callback Flow

Trigger Action

Action is triggered in async mode with max_results: 100

Auto-Pagination

Backend automatically paginates results with page_size: 10

Receive Running Callbacks

You receive 10 callbacks with:

status: RUNNING
Each containing ~10 results (may vary slightly as we filter out ads and other content)

Final Success Callback

Once the run completes, you receive one final callback with status: SUCCEEDED

Important: You may receive multiple callbacks for a single execution, and they may arrive out of order due to parallel processing. Always use the run_uid and batch_uid to track and organize your data.

Handling Callbacks & Idempotency

Since you may receive multiple callbacks (including retries), implement idempotency to prevent duplicate processing. This is crucial for maintaining data integrity in your system.

Best Practices

Track processed results using meaningful keys (e.g., linkedin_profile_id) or run_uid/batch_uid
Aggregate progressively as you receive RUNNING callbacks
Finalize only when you receive the SUCCEEDED callback

Benefits

This approach allows you to:

Stream results progressively
Handle partial failures gracefully
Ensure data consistency even with retries

Managing Callbacks

Edges provides endpoints to track, retrieve, and manage your callbacks.

Why Managing Callback History Matters

Even with a reliable setup, callbacks may not always reach your endpoint. This is often invisible without using the callback history endpoints — missing callbacks mean missing data.

If you rely solely on your callback URL logs, you might never detect missed callbacks, as they were never delivered to your system.

Common Reasons for Missed Callbacks

Network interruptions between Edges and your callback URL
Temporary downtime of your server or API endpoint
Gateway or firewall restrictions blocking Edges IPs
TLS/SSL handshake issues (expired certificates, protocol mismatch)
Slow responses from your server causing timeouts
Transient cloud provider issues on either side

How to Detect & Resolve Issues

You can use the List Callbacks endpoint to programmatically detect missing or failed callbacks:

Schedule a periodic check (e.g., once per day) to call GET /runs/callbacks filtered by status=FAILED.

For example:

curl --request GET \
  --url 'https://api.edges.run/v1/runs/callbacks?limit=20&sort=-created_at&status=FAILED' \
  --header 'X-API-Key: <your_api_key>'

The number of callbacks can be adjusted with the limit parameter up to 20. You can use the offset param if needed to paginate through results and retrieve all failed callbacks until a date.If you track the run_uid, you can also filter by run_uid to check for specific runs and verify the callbacks were successfully received run by run.

Analyze the http_status field to identify the root cause (e.g., connection refused, timeout).
If the callback reached your endpoint but ended with an error, inspect your own server logs to diagnose the issue.

http_status is the HTTP status code returned by your endpoint. It is meaningful to identify what’s happening on your callback URL. Refer to the HTTP Status Codes documentation for more details.While it will be enough to identify most issues, you may need to check your own server logs for more details in some cases:

4xx errors: Client-side issues (e.g., authentication, bad request)
5xx errors: Server-side issues (e.g., internal server error,…)

Note that you may also have “silent” failures if you have logic issues in your callback processing code that do not return an error status code but still fail to process the data correctly. So best practice is to implement explicit error handling on your endpoint and always log the received callbacks and their processing results.

Fix the issue(s) (e.g., adjust firewall, fix SSL, improve server response time).

While you can automatically replay failed callbacks, it’s crucial to understand why they failed first. This prevents flooding your endpoint with retries without fixing the underlying issue, ensures you stay within the replay limits, and guarantees you don’t miss any data.Use the replay functionality carefully — you can only replay the same callback up to 3 times.

Replay the affected callbacks with POST /runs/callbacks/{callback_uid}/replay.

Daily Monitoring Example

Recommended Daily Check: Run a cron job that:

Fetches all failed callbacks from the past 24 hours
Logs the details for investigation
Automatically retries transient failures using the replay endpoint

Regularly checking the callback history helps ensure no data is silently lost and allows you to maintain a robust, fault-tolerant integration.

Additional Use Cases for Callback History

Post-incident recovery: After downtime, retrieve missed callbacks and replay them to backfill data.
Audit & compliance: Keep a complete log of all callbacks sent and their statuses for troubleshooting or audits.
Performance monitoring: Track the proportion of successful vs failed callbacks over time to improve infrastructure reliability.

Listing Callbacks

Use GET /runs/callbacks to retrieve all callbacks with filtering and pagination: Available filters:

status: PENDING, RUNNING, FAILED, SUCCESS
run_uid: Filter by specific run
limit & offset: Pagination
sort: Sorting (prefix with - for descending)

Example: List failed callbacks

curl -X GET "https://api.edges.run/v1/runs/callbacks?status=FAILED&limit=20&sort=-created_at" \
  -H "X-API-Key: <YOUR_API_KEY>"

Getting a Specific Callback

Use GET /runs/callbacks/{callback_uid} to fetch detailed information:

Example: Get callback details

curl -X GET "https://api.edges.run/v1/runs/callbacks/{callback_uid}" \
  -H "X-API-Key: <YOUR_API_KEY>"

Replaying Callbacks

Use POST /runs/callbacks/{callback_uid}/replay to retry failed callbacks:

How replay works:

Each replay creates a new callback (up to 3 total replays)
You can only replay the original callback, not callback responses
This helps you track each attempt and identify specific issues with your webhook URL

When to use replay:

Your webhook URL was temporarily unavailable
You received a callback but want to retry processing
You need to debug callback delivery issues

Example: Replay a callback

curl -X POST "https://api.edges.run/v1/callbacks/{callback_uid}/replay" \
  -H "X-API-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json"

If you have a sandbox, you will have access to several workspaces. The API key will define the current workspace for the calls.

Next Steps

See the API Reference for detailed endpoint usage, parameters, and more examples.

Getting Started

Essentials

Managing Callbacks

What are Callbacks?

Quick Start

1. Set up your webhook endpoint

2. Configure your action call

3. Handle incoming callbacks

Understanding Async and Schedule Modes

Setting Up Callbacks

Callback Structure

Callback Payload Fields

Using `custom_data` to Track Inputs

How Callbacks Work

Callback Flow

Handling Callbacks & Idempotency

Best Practices

Benefits

Managing Callbacks

Why Managing Callback History Matters

Common Reasons for Missed Callbacks

How to Detect & Resolve Issues

Daily Monitoring Example

Additional Use Cases for Callback History

Listing Callbacks

Example: List failed callbacks

Getting a Specific Callback

Example: Get callback details

Replaying Callbacks

Example: Replay a callback

Next Steps

Getting Started

Essentials

​What are Callbacks?

​Quick Start

​1. Set up your webhook endpoint

​2. Configure your action call

​3. Handle incoming callbacks

​Understanding Async and Schedule Modes

​Setting Up Callbacks

​Callback Structure

​Callback Payload Fields

​Using custom_data to Track Inputs

​How Callbacks Work

​Parallel Processing & Pagination

​Callback Flow

​Handling Callbacks & Idempotency

​Best Practices

​Benefits

​Managing Callbacks

​Why Managing Callback History Matters

​Common Reasons for Missed Callbacks

​How to Detect & Resolve Issues

​Daily Monitoring Example

​Additional Use Cases for Callback History

​Listing Callbacks

​Example: List failed callbacks

​Getting a Specific Callback

​Example: Get callback details

​Replaying Callbacks

​Example: Replay a callback

​Next Steps

What are Callbacks?

Quick Start

1. Set up your webhook endpoint

2. Configure your action call

3. Handle incoming callbacks

Understanding Async and Schedule Modes

Setting Up Callbacks

Callback Structure

Callback Payload Fields

Using `custom_data` to Track Inputs

How Callbacks Work

Parallel Processing & Pagination

Callback Flow

Handling Callbacks & Idempotency

Best Practices

Benefits

Managing Callbacks

Why Managing Callback History Matters

Common Reasons for Missed Callbacks

How to Detect & Resolve Issues

Daily Monitoring Example

Additional Use Cases for Callback History

Listing Callbacks

Example: List failed callbacks

Getting a Specific Callback

Example: Get callback details

Replaying Callbacks

Example: Replay a callback

Next Steps