---
title: "Third-Party Integrations · RUAL Documentation"
description: "Call external APIs, keep credentials out of the canvas and handle failures."
canonical: https://docs.rual.nl/tutorials/third-party-integrations
language: en
---

# 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

- **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](https://docs.rual.nl/blueprints/system-settings-reference#custom-keys).

- **Build the request** with the http request blocks: URL, method, headers (auth from the setting), body from [`object_new_fields`](https://docs.rual.nl/block-types/object/object_new_fields) or JSON.

- **Parse the response**: map only the fields you need into your documents with [`object_update_fields`](https://docs.rual.nl/block-types/object/object_update_fields); don't mirror their whole payload.

- **Handle failure explicitly**: success/error pins → log, retry via queue for transient errors (429/5xx), alert path for permanent ones. See [error handling](https://docs.rual.nl/blueprints/block-execution#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

- Register an endpoint with [`on_startup_register_uri_post`](https://docs.rual.nl/block-types/http%20connection/on_startup_register_uri_post): your public webhook URL is `https:// /api/v1/ `.

- **Verify the sender**: shared-secret signature header, HMAC check, or an unguessable URI segment. Treat every unverified payload as hostile.

- **Reply fast** (200 with a small ack), then do the real work in the [queue](https://docs.rual.nl/blueprints/queue): senders time out and retry otherwise, giving you duplicate events.

- **Deduplicate** by event id: store received ids, skip ones you've seen (webhooks retry).

### Keeping Data in Sync

- **Pull**: [`schedule_repeating_event`](https://docs.rual.nl/block-types/events/schedule_repeating_event) polls their list endpoint on an interval and upserts by external id (update if exists, create if new. See [Storages](https://docs.rual.nl/blueprints/storage)).

- **Push**: react to local changes with [storage events](https://docs.rual.nl/blueprints/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](https://docs.rual.nl/tutorials/email-system)).

### Next Steps