Callback Payloads

Overview

What callbacks are, streaming vs final delivery, and data completeness guarantees.

Payloads

Callback JSON structure, run vs callback statuses, custom_data, and examples.

Delivery

Idempotency, missed-callback detection, and replaying failed deliveries.

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

{
  "callback_ref_uid": "string",
  "run": {
    "run_uid": "string",
    "batch_uid": "string",
    "status": "CREATED" || "INVALID" || "QUEUED" || "SCHEDULED" || "BLOCKED" || "STOPPED" || "RUNNING" || "FAILED" || "PARTIAL_SUCCEEDED" || "SUCCEEDED",
    "scheduled_run_uid": "string | null"
  },
  "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

string

Stable callback identifier that remains the same across retries. Use this for safe deduplication — even if your endpoint receives multiple retries, this identifier always refers to the same logical callback event.

object

Execution context containing run_uid (unique to the entire run), batch_uid (unique to this batch), status (current execution state), and optionally scheduled_run_uid (present when the run was triggered by a schedule — use it to correlate callbacks with scheduled runs).

object | null

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

object | null

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

object | null

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

array | null

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

Callback HTTP Headers

Webhook requests include the following HTTP headers for identification and tracking:

Header	Description
X-Callback-Ref	Stable callback identifier, identical across retries (same as `callback_ref_uid` in the payload). Use for deduplication.
X-Run-Callback	Unique identifier for each delivery attempt. Changes on every retry. Use for delivery tracking.

Use X-Callback-Ref (or callback_ref_uid in the payload) to detect and safely ignore duplicate callbacks. Use X-Run-Callback to log and debug individual delivery attempts.

Understanding Run Statuses vs Callback Statuses

It’s important to distinguish between two different types of statuses in the callback system:

Run Statuses

Run statuses (found in run.status within the callback payload) indicate the execution state of the entire run or batch. The available run statuses are:

CREATED: The run or schedule has been created but not yet queued for execution.
INVALID: The run or schedule is invalid (e.g., due to bad input or configuration).
QUEUED: The run is waiting in the queue to be executed.
SCHEDULED: The run is scheduled to execute at a future time (applies to scheduled/CRON jobs).
BLOCKED: The run stopped and is waiting on something that has to change — an invalid input, an identity that needs reconnecting, or a limit that has been reached. The cause is in error_label; see Recovering a Blocked Run.
STOPPED: The run was stopped before completion (manually or by the system).
RUNNING: The run is currently in progress.
FAILED: The run has failed. This can occur when the input seems correct, but during processing in the callback, it returns a failed status with an error (e.g., 424 – No results). In this case, the callback itself was processed correctly, even if the page doesn’t exist or returns nothing.
PARTIAL_SUCCEEDED: The run completed with some errors, but partial results are available.
SUCCEEDED: The run completed successfully.

Callback Statuses

Callback statuses (used when filtering callbacks via the API) indicate the delivery status of the callback to your webhook endpoint:

PENDING: The callback is queued and waiting to be delivered.
RUNNING: The callback has been sent to your endpoint.
FAILED: The callback delivery failed (network error, timeout, or your endpoint returned an error).
SUCCESS: The callback was successfully delivered and your endpoint returned a successful response.

Understanding BLOCKED and FAILED Run Statuses

When processing async operations, you may encounter inputs that cannot be processed. Here’s how to interpret the different scenarios:

BLOCKED Status

A run status of BLOCKED means the run stopped and is waiting on something that has to change before it can continue. The cause is in error_label. Common ones:

Invalid input — the format is wrong, or the input references a resource that doesn’t exist or isn’t accessible. For example a URL like https://www.linkedin.com/products/..., which is not a LinkedIn company page
The identity needs attention — an expired session, a login challenge, or no valid account available
A limit was reached — the run resumes once the window rolls over

The callback itself was delivered correctly; the run is what is blocked. Recovering a Blocked Run maps every error_label to its recovery.

FAILED Status (424 – No results)

A run status of FAILED with a 424 – No results error indicates that:

The input format appears correct
During processing, no results could be found for the provided input
The input may redirect to a 404 page on LinkedIn or the target resource doesn’t exist
Important: The callback itself was processed correctly by Edges, even though no results were found

Technically, when a callback returns FAILED with 424 – No results, the callback processing itself succeeded — Edges correctly processed your request and determined that no results exist. The failure is in the data retrieval, not in the callback delivery mechanism.

Using `custom_data` to Track Inputs

Callbacks let you 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/jane-doe-1a2b3c4d/",
      "custom_data": {
        "internal_id": "12345",
        "type": "lead"
      }
    },
    {
      "linkedin_profile_url": "https://www.linkedin.com/in/john-doe-9f8e7d6c/",
      "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:

{
  "callback_ref_uid": "550e8400-e29b-41d4-a716-446655440000",
  "run": { "run_uid": "...", "batch_uid": "...", "status": "RUNNING" },
  "input": {
    "linkedin_profile_url": "https://www.linkedin.com/in/jane-doe-1a2b3c4d/"
  },
  "custom_data": {
    "internal_id": "12345",
    "type": "lead"
  },
  "results": [ { "linkedin_profile_id": "...", "full_name": "Jane Doe" } ]
}

And for the second input:

{
  "callback_ref_uid": "550e8400-e29b-41d4-a716-446655440001",
  "run": { "run_uid": "...", "batch_uid": "...", "status": "RUNNING" },
  "input": {
    "linkedin_profile_url": "https://www.linkedin.com/in/john-doe-9f8e7d6c/"
  },
  "custom_data": {
    "internal_id": "671",
    "type": "lead"
  },
  "results": [ { "linkedin_profile_id": "...", "full_name": "John Doe" } ]
}

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.

Examples

Listing Callbacks

Use GET /runs/callbacks to retrieve all callbacks with filtering and pagination.

Show Available filters

status: Filter by callback delivery status. Valid values are:
- PENDING: Callbacks queued and waiting to be delivered
- RUNNING: Callbacks that have been sent to your endpoint
- FAILED: Callbacks that failed to be delivered (network errors, timeouts, or endpoint errors)
- SUCCESS: Callbacks that were successfully delivered and acknowledged by your endpoint
run_uid: Filter by specific run to see all callbacks for that run
limit & offset: Pagination controls to retrieve callbacks in batches
sort: Sorting order (prefix with - for descending, e.g., -created_at to get newest first)

Show Example: List failed callbacks

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

Getting a Specific Callback

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

Show Example: Get callback details

curl -X GET "https://api.edges.run/v1/runs/callbacks/{callback_uid}" \
  -H "Accept: application/json" \
  -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

Show Example: Replay a callback

curl -X POST "https://api.edges.run/v1/runs/callbacks/{callback_uid}/replay" \
  -H "Accept: application/json" \
  -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.

Start here

Identities

Running actions

Limits

Troubleshooting

LinkedIn specifics

SDKs & integrations

Build with Edges

Callback Payloads

Overview

Payloads

Delivery

Callback Structure

Callback Payload Fields

Callback HTTP Headers

Understanding Run Statuses vs Callback Statuses

Run Statuses

Callback Statuses

Understanding BLOCKED and FAILED Run Statuses

BLOCKED Status

FAILED Status (424 – No results)

Using `custom_data` to Track Inputs

Examples

Listing Callbacks

Getting a Specific Callback

Replaying Callbacks

Overview

Payloads

Delivery

​Callback Structure

​Callback Payload Fields

​Callback HTTP Headers

​Understanding Run Statuses vs Callback Statuses

​Run Statuses

​Callback Statuses

​Understanding BLOCKED and FAILED Run Statuses

​BLOCKED Status

​FAILED Status (424 – No results)

​Using custom_data to Track Inputs

​Examples

​Listing Callbacks

​Getting a Specific Callback

​Replaying Callbacks

Callback Structure

Callback Payload Fields

Callback HTTP Headers

Understanding Run Statuses vs Callback Statuses

Run Statuses

Callback Statuses

Understanding BLOCKED and FAILED Run Statuses

BLOCKED Status

FAILED Status (424 – No results)

Using `custom_data` to Track Inputs

Examples

Listing Callbacks

Getting a Specific Callback

Replaying Callbacks