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.