Webhooks

​

Delivery Models

​

Job Run Webhooks

​

Event Trigger Webhooks

​

Delivery Lifecycle

1. Terminal State Reached: When a run finishes, the executor checks if the parent Job has a webhook_url configured.
2. Payload Construction: A WebhookPayload is assembled containing the run’s final state, result, and error (if any).
3. Signing: If a webhook_secret is configured, the payload is signed using HMAC-SHA256 with a timestamp for replay protection.
4. Dispatch: An HTTP POST request is sent to the webhook_url.
5. Retry Logic: If delivery fails, Strait retries based on the response status code.
6. Dead Letter: After exhausting retries, deliveries are marked as dead (event trigger) or silently dropped (job run).

​

Webhook Payload

​

HMAC-SHA256 Signing

• X-Strait-Timestamp: Unix timestamp used in signature generation
• X-Strait-Signature: sha256=<signature>
• X-Webhook-Signature: compatibility header for existing consumers

signed_payload = "{unix_timestamp}.{raw_json_body}"
signature      = HMAC-SHA256(webhook_secret, signed_payload)

​

Verifying Signatures (Go Example)

func verifySignature(payload []byte, timestamp string, signatureHeader string, secret string) bool {
    if !strings.HasPrefix(signatureHeader, "sha256=") || timestamp == "" {
        return false
    }
    actualSig := signatureHeader[7:]

    mac := hmac.New(sha256.New, []byte(secret))
    mac.Write([]byte(timestamp + "."))
    mac.Write(payload)
    expectedSig := hex.EncodeToString(mac.Sum(nil))

    return hmac.Equal([]byte(actualSig), []byte(expectedSig))
}

​

Retry Strategy

​

Job Run Webhooks

• Attempt 1: Immediate
• Attempt 2: 1 second delay
• Attempt 3: 5 seconds delay

​

Event Trigger Webhooks

• Max attempts: 5
• Backoff: Exponential — 5s, 25s, 125s, 625s (capped at 30 minutes)
• Delivery worker: Polls the database every 5 seconds for pending deliveries

​

Retry Rules

• Client Errors (4xx): Delivery is considered a permanent failure; no retries are attempted. The delivery is dead-lettered immediately.
• Server Errors (5xx) / Timeouts: Delivery is retried up to the maximum attempt limit.
• Context Cancellation: If the system is shutting down, delivery may be aborted with a “context canceled” error.

​

Configuration

​

Job Webhooks

• webhook_url: The destination for the POST request.
• webhook_secret: (Optional) The key used for HMAC signing.

​

Event Trigger Webhooks

• notify_url: Set when creating a wait-for-event step or SDK call.
• Delivery status is tracked in the webhook_deliveries table with event_trigger_id.

​

Dead Letter Queue (DLQ) Management

# List all failed deliveries for a project
curl "https://strait.dev/v1/webhook-deliveries?project_id=proj_1&status=failed" \
  -H "Authorization: Bearer strait_..."

# Retry a specific failed delivery
curl -X POST https://strait.dev/v1/webhook-deliveries/{deliveryID}/retry \
  -H "Authorization: Bearer strait_..."