Wait/Signal

Wait/Signal lets you create tasks that pause in a “waiting” state after executing their callback, then resume when your system - or a third party - sends a signal. This is useful for human-in-the-loop workflows, payment confirmations, external approvals, and multi-step processes that depend on outside events.

How It Works

1. Create a task with waitForSignal: true
2. AsyncQueue calls your callback URL as usual
3. Instead of completing, the task transitions to waiting and returns a signalToken
4. When you’re ready, send a signal with the token to complete or fail the task
5. If no signal arrives within maxWaitTime, the task times out automatically

Your App                    AsyncQueue                  Your Callback
  │                            │                            │
  │── POST /v1/tasks ─────────▶│                            │
  │   waitForSignal: true      │                            │
  │◀── 201 { signalToken } ───│                            │
  │                            │── HTTP callback ──────────▶│
  │                            │◀── 200 OK ────────────────│
  │                            │   (status: "waiting")      │
  │                            │                            │
  │  ... time passes ...       │                            │
  │                            │                            │
  │── POST /v1/signals/:token ▶│                            │
  │   { status: "completed" }  │                            │
  │◀── 200 { task } ──────────│                            │

Creating a Wait/Signal Task

Add waitForSignal: true to your task creation request. The response includes a one-time signalToken.

curl -X POST https://api.asyncqueue.io/v1/tasks \
  -H "X-API-Key: async_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "targetUrl": "https://your-api.com/start-process",
    "method": "POST",
    "body": "{\"orderId\": \"order_123\"}",
    "waitForSignal": true,
    "maxWaitTime": 3600,
    "onCompleteUrl": "https://your-api.com/webhook"
  }'

Response:

{
  "task": {
    "id": "019d2b00-1234-7000-a000-000000000001",
    "status": "pending",
    "waitForSignal": true,
    "maxWaitTime": 3600
  },
  "signalToken": "a1b2c3d4e5f6..."
}

Important: Store the signalToken securely. It is returned only once at creation time and never again.

Sending a Signal

When you’re ready to resolve the task, send a POST request to the signal endpoint. No API key is required - the token itself authenticates the request.

Complete a task

curl -X POST https://api.asyncqueue.io/v1/signals/a1b2c3d4e5f6... \
  -H "Content-Type: application/json" \
  -d '{
    "status": "completed",
    "result": { "downloadUrl": "https://cdn.example.com/output.pdf" }
  }'

Fail a task

curl -X POST https://api.asyncqueue.io/v1/signals/a1b2c3d4e5f6... \
  -H "Content-Type: application/json" \
  -d '{
    "status": "failed",
    "error": "Payment was declined"
  }'

Signal Request Body

Field	Type	Required	Description
status	string	Yes	"completed" or "failed"
result	any	No	Result data (for completed signals)
error	string	No	Error message (for failed signals)

Task Lifecycle

A wait/signal task goes through these states:

Status	Description
pending	Task created, waiting to be processed
processing	Callback URL is being called
waiting	Callback succeeded, waiting for external signal
completed	Signal received with status: "completed"
failed	Signal received with status: "failed"
timeout	No signal received within maxWaitTime
cancelled	Task was cancelled (waiting tasks can be cancelled)

Start Result vs Final Result

Wait/signal tasks have two result fields:

• startResult - The HTTP response from the initial callback (stored when task enters “waiting”)
• result - The final result provided by the signal

This lets you capture data from both the initial callback and the signal resolution.

Timeouts

If no signal arrives within maxWaitTime seconds (default: 30), the task automatically transitions to timeout status. Set a longer maxWaitTime for processes that take more time:

{
  "targetUrl": "https://your-api.com/start",
  "waitForSignal": true,
  "maxWaitTime": 86400
}

This gives the task 24 hours to receive a signal.

Cancelling Waiting Tasks

Tasks in the waiting state can be cancelled like pending or delayed tasks:

curl -X POST https://api.asyncqueue.io/v1/tasks/{taskId}/cancel \
  -H "X-API-Key: async_your_key"

Cancelling a waiting task invalidates its signal token and removes the timeout watchdog.

Use Cases

• Payment confirmations - Start a checkout, wait for payment webhook from Stripe/PayPal
• Human approvals - Trigger a review process, wait for a manager to approve or reject
• File processing - Upload a file to a converter, wait for the conversion to finish
• Third-party integrations - Start an external process, wait for a callback when done
• Multi-step workflows - Chain steps where each depends on an external event

Security

• Signal tokens are 256-bit random values (64 hex characters)
• Only the SHA-256 hash is stored, the raw token is returned once
• Tokens are one-time use and invalidated after signaling
• Tokens auto-expire based on maxWaitTime
• The signal endpoint is rate-limited by IP (30 requests per minute)