Relay API Reference

All endpoints require a Bearer token. See Authentication.

See Rate Limits for per-tier request limits.

POST /v1/relay

Schedule a webhook to be delivered after a delay.

Request body:

{
  target_url: string    // URL to send webhook to
  method: string        // HTTP method (POST, PUT, PATCH, etc.)
  delay: string         // Human-readable delay (30s, 5m, 2h, 7d)
  payload: object       // JSON payload to send
  headers: object       // Custom headers to include
}

Example:

curl -X POST https://api.solenoid.systems/v1/relay \
  -H "Authorization: Bearer sm_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "target_url": "https://your-app.com/webhooks",
    "method": "POST",
    "delay": "5m",
    "payload": {
      "event": "trial_expiring",
      "user_id": "user_123"
    },
    "headers": {
      "X-Event-Type": "trial_expiring"
    }
  }'

Response (201 Created):

{
  "relay_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "scheduled_for": 1706123456789,
  "status": "scheduled"
}

Response fields:

• relay_id — unique identifier for this webhook.
• scheduled_for — Unix timestamp in milliseconds when webhook will fire.
• status — always "scheduled" on success.

Webhook delivery

When the delay expires, Relay sends the payload to your target URL.

Delivered request:

POST /webhooks HTTP/1.1
Host: your-app.com
Content-Type: application/json
X-Solenoid-Signature: abc123def456...
X-Solenoid-Timestamp: 1706123456789
X-Event-Type: trial_expiring

{
  "event": "trial_expiring",
  "user_id": "user_123"
}

Headers added by Relay:

• X-Solenoid-Signature — HMAC-SHA256 of timestamp + payload.
• X-Solenoid-Timestamp — Unix timestamp in milliseconds when sent.

Custom headers are applied after signature headers and cannot override them.

Delay validation

Minimum: 1 second. Maximum: 30 days. Value must be a positive integer followed by a unit.

Signature verification

Verify delivered webhooks with HMAC-SHA256:

1. Extract X-Solenoid-Signature and X-Solenoid-Timestamp headers.
2. Reconstruct the signed content: timestamp + JSON.stringify(body).
3. Compute HMAC-SHA256 using your API key as the secret.
4. Compare the computed signature with the received signature.

Retry logic

• 5xx errors — retried up to 3 times with exponential backoff.
• Network errors — retried up to 3 times with exponential backoff.
• 4xx errors — logged and removed, no retry.
• 2xx/3xx — success, webhook removed.

Metering

Next steps

• Quick Start — schedule your first webhook
• Errors — error codes and resolution
• Pricing — upgrade your plan