Rocketly API

Use the webhook and source-management endpoints to securely send leads from your web forms into Rocketly.

Key Features

Secure Authentication

Management endpoints are protected with JWT; the inbound webhook endpoint is verified with a source key. Never put a management token in the browser, and regenerate a source key if it is exposed.

Inbound lead capture

Send data from a form or server-side integration to an authenticated webhook source.

Source management

Authorized users can create and list sources, then manage the available field mapping options.

Source health

Review each source's 24-hour health information and investigate problem deliveries.

Webhook Integration

Use a source-specific webhook URL and tracker script to capture leads from your website.

Delivery logs

Inspect source-level request logs to review inbound traffic and diagnose failed deliveries.

API Endpoints

Webhook & Form Integration

POST/api/webhook/lead/{api_key}Receive lead from web form

GET/api/webhook/sourcesList webhook sources

POST/api/webhook/sourcesCreate webhook source

GET/api/webhook/sources/{source_id}/healthView the source's last 24-hour health

GET/api/webhook/sources/{source_id}/logsReview source delivery logs

GET/api/webhook/tracker.jsWebsite tracking script

Safe setup flow

This page documents Rocketly's inbound lead-capture integration. Management endpoints require a signed-in user, an eligible plan feature and the settings.integrations permission.

Create a source. In Settings > Integrations, create a webhook source; its generated URL accepts inbound leads only.
Test the delivery. From your server or form provider, send a test payload to POST /api/webhook/lead/{api_key}.
Review health and logs. Check delivery logs and the source's 24-hour health view; regenerate the source key if it is exposed.

Example Usage

cURL - Create Lead

curl -X POST https://api.gorocketly.com/api/webhook/lead/YOUR_API_KEY \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "John",
    "last_name": "Doe",
    "phone_raw": "+1234567890",
    "email": "[email protected]",
    "status": "Open"
  }'

Authentication

There are two separate authentication paths: a session token or a personal access token (PAT) for the management endpoints, and a per-source key for the inbound webhook endpoint.

Personal access token. The token is issued with an fl_pat_ prefix and shown exactly once, at creation; only its digest is stored on the server. Send it in either header: Authorization: Bearer fl_pat_… or X-API-Key: fl_pat_….
Scopes. If the scope list is left empty, the token reaches as far as the user's own permissions. When scopes are given, the effective permission is the INTERSECTION with the user's permissions — a scope can never grant a permission the user does not have. Wildcards such as leads.* and * are supported; an unrecognised scope is rejected with 422.
Lifetime and revocation. expires_in_days accepts 1–365 days; left empty, the token never expires. A token is revoked immediately with DELETE /api/pat/{token_id}. Invalid or revoked credentials return 401 with a WWW-Authenticate: Bearer header.
Inbound webhook endpoint. This endpoint authenticates the request with the source key in the URL, not with a body signature. The key is issued with an flwh_ prefix, stored as a SHA-256 digest, and compared in constant time (timing-safe). There is no separate signature header, so treat the webhook URL as a secret and rotate it from the source settings if you suspect it has leaked.
Additional restrictions. Each source can define an IP and domain allow list; a request from outside those lists receives 403.

Personal Access Tokens

POST/api/patCreate a token (plain value returned once)

GET/api/patList tokens, masked

DELETE/api/pat/{token_id}Revoke a token

Rate limits

Rate limiting is applied both per endpoint and platform-wide. Do not try to predict your remaining budget; read it from the headers on every response.

Inbound lead endpoint. 60 requests per minute per source key. Once exceeded, the endpoint returns 429 with Retry-After: 60.
General quota. The default for other endpoints is 100 requests per minute; some endpoints are tighter.
Headers. Every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset; a 429 response also includes Retry-After.
429 body. Contains the error, limit, remaining and retry_after fields. Wait for the Retry-After value before retrying.
Body size. An inbound lead request may be at most 100 KB; a larger request is rejected with 413.

Responses and error codes

The inbound lead endpoint reports the business outcome in the status field of the body rather than in the HTTP status code; a successful request always returns 200.

created. A new lead was created; the body returns its lead_id.
updated. The record was found to be a duplicate; no new record is opened, the existing lead is updated and its lead_id is returned.
spam. The request was flagged as spam; no lead is created.
error. At least one of the phone or email fields is required; if neither is present, the body returns success: false.
Error codes. 400 unreadable or invalid body · 403 outside the IP/domain allow list · 404 invalid or disabled webhook key · 413 body exceeds 100 KB · 429 rate limit.
Opened in a browser. A GET to the same URL creates no lead; the endpoint returns an informational JSON describing the expected body.

Versioning

All endpoints are published under the /api base path. New surfaces are added under an explicit /api/v2 prefix without breaking live paths; existing paths such as /api/webhook/… stay where they are. Keep the base address in your integration as a single configuration value instead of hard-coding path prefixes.

Get Started Now

Create an account, use an eligible workspace plan and permission to create a webhook source, then add its URL to your secure integration layer.