Connect n8n

Brault has no native n8n app yet (it is on the roadmap). You do not need one: n8n's webhook trigger receives Brault events, and its HTTP step calls any /v1 route with your API key. This guide wires both directions.

You need an API key with webhooks:manage (to register the endpoint) and files:write (for the import example). Create one under Settings → Developers in the app, see Get an API key.

1. Trigger an n8n workflow from a Brault event

Start the workflow with a Webhook node set to POST. n8n shows a test URL and a production URL; register the production one with Brault (the test URL only listens while you are testing in the editor).

Register that URL as a Brault webhook endpoint. The URL must be https:// on port 443 (or 8443) and publicly reachable, which is true for n8n Cloud and for a self-hosted n8n behind a public HTTPS domain.

curl -X POST https://us.api.brault.app/v1/webhooks \
  -H "Authorization: Bearer $BRAULT_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 8f14e45f-2222-4c1a-9c1e-n8n-hook" \
  -d '{
    "url": "<the URL n8n gave you>",
    "name": "n8n workflow",
    "events": ["file.created", "comment.created", "transfer.downloaded"]
  }'

Pick any tokens from the event catalogue, or ["*"] for everything. Then send a test delivery so n8n has a sample payload to map fields from:

curl -X POST https://us.api.brault.app/v1/webhooks/<webhook_id>/test \
  -H "Authorization: Bearer $BRAULT_API_KEY"

Every delivery body is the event envelope: type, occurred_at, actor, and a minimal data snapshot with the ids you need for the next step. Deliveries are at-least-once with no ordering guarantee, so deduplicate on id if a duplicate would matter to your workflow.

Before production traffic, verify the Brault-Signature header. In n8n that is a Code node placed right after the Webhook node, running the JavaScript verification from the Webhooks page against the raw body and the secret returned when you created the endpoint. Reject the execution when it does not match.

2. Call the Brault API from n8n

Use an HTTP Request node. Create a Header Auth credential with name Authorization and value Bearer bsk_…, and attach it to the node so the key never appears in the workflow JSON.

Set the method and URL from the reference, body content type JSON, and map fields from earlier nodes with expressions.

The example below imports a file that another step produced (any public http(s) URL) into a Brault library:

POST https://us.api.brault.app/v1/files/import
Authorization: Bearer <your key>
Content-Type: application/json
Idempotency-Key: <a unique value per run, e.g. the workflow execution id>

{
  "url": "https://example.com/exports/hero-v3.psd",
  "name": "hero-v3.psd",
  "library_id": "<library_id>"
}

The response is 202 with an import object: status starts at queued, and file_id is set once it reaches succeeded. Either poll GET /v1/imports/<import_id> from a later step, or let Brault call you back: subscribe the endpoint from section 1 to import.completed and import.failed (a successful import also emits a normal file.created). Imports are capped at 5 GiB and 2 concurrent per brandspace.

Anything else in the reference works the same way: same base URL, same header, JSON in and out. Use Idempotency-Key on every POST that creates something, so a retried run does not create it twice.

3. Rate limits and errors

n8n retries failed HTTP steps on its own schedule. Brault answers 429 with a Retry-After header when a bucket or the monthly quota is hit, and every error carries a request_id you can quote to support. See Rate limits and Conventions.