Cuvellis is a webhook relay platform. You give Cuvellis your inbound URL to any external service (Stripe, GitHub, Shopify, etc.) and Cuvellis guarantees reliable, traceable delivery of every event to your own endpoint — with automatic retries, quota tracking, and failure monitoring.
Table of Contents
How it works
External service (Stripe, GitHub…)
│
│ POST https://api.cuvellis.com/webhooks/receive/{token}
▼
[ Cuvellis ] ── quota check ── relay as-is ──▶ Your target URL
- ✦You register a webhook in the Dashboard → Webhooks: provide a name and your target URL.
- ✦Cuvellis generates a unique inbound URL for that webhook.
- ✦You give this inbound URL to Stripe (or any external service) as your webhook endpoint.
- ✦When the external service fires an event, it POSTs to your inbound URL.
- ✦Cuvellis validates the token, checks your monthly quota, and responds 202 Accepted immediately.
- ✦The event — payload and original headers — is forwarded as-is to your target URL.
Creating a Webhook
From the dashboard, click New Webhook and fill in:
| Field | Description |
|---|---|
| Name | A label to identify this webhook (e.g. Stripe Production) |
| Target URL | Your HTTPS endpoint that will receive the relayed events |
After creation, you'll see your unique Inbound URL:
https://api.cuvellis.com/webhooks/receive/{token}
Give this URL to the external service as its webhook destination.
Receiving Events
Cuvellis forwards the event exactly as received from the external service — the original payload and headers are preserved. One header is added:
X-Request-Id: 550e8400-e29b-41d4-a716-446655440000
Your endpoint must return a 2xx status code within 30 seconds to confirm delivery. Any other response triggers a retry.
Inbound responses
When the external service posts to your inbound URL, Cuvellis responds:
| Status | Meaning |
|---|---|
202 Accepted | Event queued for delivery |
404 Not Found | Token unknown or webhook disabled |
429 Too Many Requests | Monthly event quota exceeded |
Retry Logic
If your endpoint does not return a 2xx response, Cuvellis retries automatically using exponential backoff with jitter:
| Attempt | Approximate delay |
|---|---|
| 1 | ~30 seconds |
| 2 | ~1 minute |
| 3 | ~2 minutes |
| 4 | ~4 minutes |
| 5 | ~8 minutes |
| … | … |
| 10 (final) | up to 6 hours |
Permanent failures (status 400, 401, 403, 404, 410) are not retried — they indicate a misconfiguration on your side.
Transient failures (5xx, timeouts, network errors) are retried up to 10 times.
After 10 consecutive failures, the webhook is automatically disabled. You can re-enable it from the dashboard.
Plan Limits
| Plan | Max Webhooks | Max Events / month |
|---|---|---|
| Basic | 3 | 1 000 |
| Pro | 20 | 50 000 |
| Ultra | 100 | 500 000 |
| Enterprise | Custom | Custom |
When your monthly event quota is reached, inbound requests return 429 until the next billing cycle.
To increase your limits, upgrade your plan from Dashboard → Billing.
Best Practices
Respond quickly — return 2xx immediately and process the event asynchronously. Cuvellis waits up to 30 seconds before treating a delivery as failed.
Verify the original signature — Cuvellis forwards the original headers untouched, including any signature header from the external service (e.g. Stripe-Signature). Verify it against the secret you have with that service, not with Cuvellis.
Handle duplicates — due to at-least-once delivery, your endpoint may occasionally receive the same event more than once. Use the X-Request-Id header as an idempotency key.
Use HTTPS — Cuvellis only delivers to http:// or https:// endpoints. Internal/private IP addresses are blocked.
Monitor failures — if your endpoint returns errors consistently, it will be automatically disabled after 10 failures. Check the failure count in the dashboard.