OpenClaw Integration

Use Basin as the secure form intake layer for your OpenClaw AI agents.

OpenClaw agents need clean, structured, spam-free input before they can reason and act. Basin handles secure form ingestion, spam filtering, and delivery — so your agents receive only high-quality submissions to work with.

There are two delivery patterns to choose from, which can be combined:

Webhooks — Basin pushes each submission to OpenClaw in real time
Polling — OpenClaw pulls unread submissions from the Basin API on a schedule

Step 1: Create and Configure Your Basin Form

Create a new form in your Basin dashboard.
Find your Form API Key under Form → Integrations → Form API Key. Use a form-specific key to limit access to submissions for that form only.

For spam filtering options, see the Spam Protection Overview.

Step 2: Add Basin to Your Website

Point your form's action attribute to your Basin endpoint:

<form action="https://usebasin.com/f/YOUR_FORM_ID" method="POST">
  <input type="text" name="name" required />
  <input type="email" name="email" required />
  <textarea name="message" required></textarea>
  <button type="submit">Submit</button>
</form>

See HTML Form Backend for full setup options.

Step 3: Choose Your Delivery Pattern

Option A: Webhooks (Real-Time)

Configure a webhook in Basin to push submissions to your OpenClaw instance the moment they arrive.

Go to Form → Integrations → Webhooks and create a new webhook.
Set the URL to your OpenClaw webhook endpoint.
Choose your spam strategy (see below).
Enable Webhook Signing and validate the X-Basin-Signature header in OpenClaw to confirm requests are genuine.

See the Webhooks guide for full configuration details, including payload formats and signature verification.

Option B: Polling (Scheduled / Fallback)

OpenClaw can periodically pull unread submissions from the Basin API. This is useful as a fallback if a webhook delivery fails, or for batch processing workflows.

Fetch unread submissions

GET https://usebasin.com/api/v1/submissions?unread=true&form_id=YOUR_FORM_ID
Authorization: Bearer YOUR_API_KEY

To fetch only non-spam unread submissions:

GET https://usebasin.com/api/v1/submissions?filter_by=new&form_id=YOUR_FORM_ID
Authorization: Bearer YOUR_API_KEY

filter_by=new returns submissions that are unread, not spam, and not trashed.

Mark a submission as read after processing

PATCH https://usebasin.com/api/v1/submissions/SUBMISSION_ID
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{ "submission": { "read": true } }

Marking submissions as read after processing prevents them from being picked up again on the next poll, making the Basin API behave as a durable, idempotent queue.

See the API Reference for full endpoint documentation.

Spam Strategy

By default, Basin only triggers webhooks for submissions that pass spam filtering. You can change this in the webhook settings:

Strategy	When to use
Ham only (default)	Your agents only need clean, actionable submissions
Ham + spam	You want OpenClaw to analyse spam patterns or handle triage

For polling, use ?filter_by=new for ham-only, or omit filter_by and use ?spam_status=false / ?spam_status=true to fetch each category separately.

Securing the Integration

Use Form API Keys, not account-wide keys — see Authentication & Tokens
Validate webhook signatures on every inbound request — see Webhooks: Signing
Rotate keys if compromised from the Integrations page in your Basin dashboard

Webhooks — full webhook configuration and signing reference
API Reference — full API documentation
Authentication & Tokens — API key types and scoping
Spam Protection Overview — available spam controls