Third-Party Integrations

By the end your blueprint can call an external API, receive its webhooks, keep data in sync and survive failures, with the credentials off the canvas.

Outbound: your blueprint calls their API

1. Credentials first

   When the service has a provider type, configure a service provider and name it on the block: the key stays on the cluster and never enters the run. For anything else, store the key as a secure system setting (e.g. stripe_secret_key) and read it with value_get_system_key_select (get setting). Never in the blueprint. See custom keys.

2. Build the request

   Use the request blocks: function_trigger_webhook_http_get_json (Request: GET JSON), function_trigger_webhook_http_post (Request: POST json) and their siblings in the webhooks group. Set the url, the headers or auth from the setting, and a body from object_new_fields (new object).

3. Parse the response

   Map only the fields you need from response into your documents with object_update_fields (update existing object). Do not mirror their whole payload.

4. Handle failure explicitly

   Branch on the code pin: log, retry via the queue for transient errors (429, 5xx), and take an alert path for permanent ones. See error handling.

Inbound: their service calls yours

1. Register an endpoint

   on_startup_register_uri_post (on api post) gives you a public webhook URL: https://<cluster>/api/v1/<uri>.

2. Verify the sender

   A shared-secret signature header, an HMAC check or an unguessable URI segment. Treat every unverified payload as hostile.

3. Reply fast

   Answer 200 with a small ack, then do the real work in the queue. Otherwise senders time out and retry, which gives you duplicate events.

4. Deduplicate

   Store received event ids and skip the ones you have seen, because webhooks retry.

Keeping data in sync needs one system of record

• Pull: schedule_repeating_event (repeating event) polls their list endpoint on an interval and upserts by external id with function_upsert_document_from_mutations (upsert document). 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.

Rules that keep an integration alive

• Rotate credentials by editing the service provider or the system setting. Every flow picks it up on its next run, with 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