Third-Party Integrations

Calling external APIs from blueprints, receiving webhooks, storing credentials safely, and keeping integrations alive.

Most integrations are one of two shapes: your blueprint calls their API, or their service calls yours (a webhook). RUAL handles both with the same primitives. This tutorial sets up a real one end to end and covers the operational rules that keep it healthy.

Outbound: Calling Their API

1. Credentials first — store the API key/token as a secure system setting (e.g. stripe_secret_key), never in the blueprint. Read it with get system setting — see custom keys.
2. Build the request with the http request blocks: URL, method, headers (auth from the setting), body from object_new_fields or JSON.
3. Parse the response — map only the fields you need into your documents with object_update_fields; don't mirror their whole payload.
4. Handle failure explicitly — success/error pins → log, retry via queue for transient errors (429/5xx), alert path for permanent ones. See error handling.

Many popular services have ready-made block groups (postmark, mailchimp, discord, twilio) — search the service name in the block library before building raw http requests.

Inbound: Receiving Webhooks

1. Register an endpoint with on_startup_register_uri_post — your public webhook URL is https://<cluster>/api/v1/<uri>.
2. Verify the sender — shared-secret signature header, HMAC check, or an unguessable URI segment. Treat every unverified payload as hostile.
3. Reply fast (200 with a small ack), then do the real work in the queue — senders time out and retry otherwise, giving you duplicate events.
4. Deduplicate by event id: store received ids, skip ones you've seen (webhooks retry).

Keeping Data in Sync

• Pull: schedule_repeating_event polls their list endpoint on an interval and upserts by external id (update if exists, create if new — see Storages).
• Push: react to local changes with storage events and forward them to the service.
• Conflict rule: pick one system of record per field and write it down in the flow's comments — two-way sync without it always corrupts something.

Operational Rules

• Rotate credentials by editing the system setting — every flow picks it up next run, no blueprint edits.
• Log every outbound call (endpoint, status, duration) during rollout; sample it later.
• Respect their rate limits with queue debounce instead of bursts.
• Build a tiny health check: a scheduled call that verifies the token still works, and alerts via your own email flow (Email System Setup).

Next Steps

Remote Access Control Securing the webhooks you expose. Queue Retries, debounce, and background sync work. Common Blueprint Patterns Auth and error-handling recipes for your calls.

Was this page helpful? Tell us what to improve · RUAL Docs is an integral component of the RUAL ecosystem