This feature is currently in beta and requires the parallel-beta: webhook-2025-08-12 header when using the Task API.

Overview

Webhooks allow you to receive real-time notifications when your Parallel Task Runs complete, eliminating the need for constant polling—especially for long-running or research-intensive tasks. Our webhooks follow standard webhook conventions to ensure security and interoperability. You can view and manage the secret keys used to sign webhook calls in Settings → Webhooks.

Setup

1. Record your webhook secret

Go to Settings → Webhooks to view your account webhook secret.

2. Configure Webhook in Task Run Request

To register a webhook for a task run, include a webhook parameter in your task run creation request:
curl --request POST \
  --url https://api.parallel.ai/v1/tasks/runs \
  --header "Content-Type: application/json" \
  --header "parallel-beta: webhook-2025-08-12" \
  --header "x-api-key: PARALLEL_API_KEY" \
  --data '{
    "task_spec": {
      "output_schema": "Find the GDP of the specified country and year"
    },
    "input": "France (2023)",
    "processor": "core",
    "metadata": {
      "key": "value"
    },
    "webhook": {
      "url": "https://your-domain.com/webhooks/parallel",
      "event_types": ["task_run.status"]
    }
  }'

Webhook Parameters

ParameterTypeRequiredDescription
urlstringYesYour webhook endpoint URL. Can be any domain.
event_typesarray[string]YesCurrently only ["task_run.status"] is supported.
Use Settings → Webhooks to view or rotate your account webhook secret.

Webhook Events

Task Run Status

We currently support task_run.status event on task run completions. When a task run finishes, either with a success or a failure, we will send a POST request to your configured webhook endpoint.

Response Format

Request Headers

Your webhook endpoint will receive requests with these headers:
  • webhook-id: Unique identifier for each webhook event
  • webhook-timestamp: Unix timestamp in seconds
  • webhook-signature: One or more versioned signatures, e.g. v1,<base64 signature> v1,<base64 signature>
{
  "Content-Type": "application/json",
  "webhook-id": "whevent_abc123def456",
  "webhook-timestamp": "1751498975",
  "webhook-signature": "v1,K5oZfzN95Z9UVu1EsfQmfVNQhnkZ2pj9o9NDN/H/pI4="
}
Signatures are space-delimited per the Standard Webhooks format. The webhook-signature header can include multiple entries separated by spaces; you should check each entry until you find one which matches the signature generated by your webhook secret. Under normal circumstances there will only be one signature in the webhook-signature header, but there may be multiple if you rotate your webhook secret without immediately expiring the old secrets.
webhook-signature: v1,BASE64SIG_A v1,BASE64SIG_B

Webhook Payload Structure

Each webhook payload contains the following fields:
  • timestamp: ISO 8601 timestamp of when the event occurred
  • type: Event type (currently only task_run.status is supported)
  • data: Event-specific payload. For the ‘task_run.status’ event, it is the complete Task Run object

Example Payloads

The following examples demonstrate the payload structure for completed and failed task runs:
Success
{
  "timestamp": "2025-04-23T20:21:48.037943Z",
  "type": "task_run.status",
  "data": {
    "run_id": "trun_9907962f83aa4d9d98fd7f4bf745d654",
    "status": "completed",
    "is_active": false,
    "warnings": null,
    "error": null,
    "processor": "core",
    "metadata": {
      "key": "value"
    },
    "created_at": "2025-04-23T20:21:48.037943Z",
    "modified_at": "2025-04-23T20:21:48.037943Z"
  }
}
Failure
{
  "timestamp": "2025-04-23T20:21:48.037943Z",
  "type": "task_run.status",
  "data": {
    "run_id": "trun_9907962f83aa4d9d98fd7f4bf745d654",
    "status": "failed",
    "is_active": false,
    "warnings": null,
    "error": {
      "message": "Task execution failed",
      "details": "Additional error details"
    },
    "processor": "core",
    "metadata": {
      "key": "value"
    },
    "created_at": "2025-04-23T20:21:48.037943Z",
    "modified_at": "2025-04-23T20:21:48.037943Z"
  }
}

Security & Reliability

HMAC Signature Verification

Webhook requests are signed using HMAC-SHA256 with standard Base64 (RFC 4648) encoding with padding. The signature header is formatted as v1,<base64 signature> where <base64 signature> is computed over the payload below.
<webhook-id>.<webhook-timestamp>.<payload>
Where:
  • <webhook-id>: The value of the webhook-id header
  • <webhook-timestamp>: The value of the webhook-timestamp header
  • <payload>: The exact JSON body of the webhook request
You must parse the version and the signature before verifying. The webhook-signature header uses space-delimited signatures; check each signature until one matches. Here’s how ou may verify the signature:
import base64, hashlib, hmac

def compute_signature(secret: str, webhook_id: str, webhook_timestamp: str, body: bytes) -> str:
    payload = f"{webhook_id}.{webhook_timestamp}.{body.decode()}".encode()
    digest = hmac.new(secret.encode(), payload, hashlib.sha256).digest()
    return base64.b64encode(digest).decode()  # standard Base64 with padding

def is_valid_signature(webhook_signature_header: str, expected_signature: str) -> bool:
    # Header may contain multiple space-delimited entries; each is "v1,<sig>"
    for part in webhook_signature_header.split():
        _, sig = part.split(",", 1)
        if hmac.compare_digest(sig, expected_signature):
            return True
    return False

Retry Policy

Webhook delivery uses the following retry configuration:
  • Initial delay: 5 seconds
  • Backoff strategy: Exponential backoff (doubles per failed request)
  • Maximum retries: Multiple attempts over 48 hours
After exhausting all retry attempts, webhook delivery for that event is terminated.

Best Practices

Be sure to set up your webhook endpoint so that you:

1. Always Return 2xx Status

Your webhook endpoint should return a 2xx HTTP status code to acknowledge receipt. Any other status code will trigger retries.

2. Verify Signatures

Always verify HMAC signatures using your account webhook secret from Settings → Webhooks to ensure webhook authenticity. Ensure that you are calculating signatures using the proper process as shown above.

3. Handle Duplicates

Although not common, duplicate events may be sent to the configured webhook URL. Ensure your webhook handler can detect and safely ignore duplicate events.

4. Process Asynchronously

Process webhook events asynchronously to avoid timeouts and ensure quick response times.