Use BrezelScraper with n8n

Start with the API-first workflow. It is easier to test and easier to debug. Add webhooks later if you want BrezelScraper to notify n8n when jobs finish.

Before you start

Make sure you have:

A BrezelScraper account with credits
An API key from Dashboard > Integrations
An n8n workflow you can edit and activate

Workflow overview

Trigger --> HTTP Request (create job) --> Wait --> HTTP Request (poll status)
                                                        |
                                          +---------+---+----------+
                                          |         |              |
                                      completed   running       failed
                                          |       / pending    / cancelled
                                          v      v              v
                                  HTTP Request  loop back     stop or
                                  (get results) to Wait       handle error

Step 1: create an API key

In BrezelScraper, open Dashboard > Integrations and create a new API key. Copy the full bscraper_... token and store it somewhere safe. You will only see it once.

Step 2: create a job with an HTTP Request node

Add an HTTP Request node with these settings:

Method: POST
URL: https://api.brezelscraper.com/api/v1/jobs
Authentication: generic header auth, or add the header manually
Header option 1: Authorization: Bearer bscraper_your_key_here
Header option 2: X-API-Key: bscraper_your_key_here
Body content type: JSON

Example request body:

{
  "name": "Berlin cafes",
  "keywords": ["cafes in berlin"],
  "lang": "en",
  "depth": 5,
  "max_results": 100,
  "reviews_max": 0,
  "images_max": 0,
  "max_time": 1800
}

Field	Type	Notes
`name`	string	A label for this job (required)
`keywords`	string[]	1 to 5 search terms (required)
`lang`	string	Two-letter language code (required)
`depth`	int	Scroll depth, 1—20 (default 5)
`max_results`	int	Cap on results, 1—500
`reviews_max`	int	Reviews per place, 0—500
`images_max`	int	Total images across all places, 0—40000
`max_time`	int	Timeout in seconds, up to 3600 (default 1800)

A successful 201 Created response returns the new job ID:

{
  "id": "d8d8a24e-cef2-4b02-8396-abc290b6f299"
}

Step 3: keep the job ID in your workflow

Store the id from the response in a field such as jobId so later nodes can reference it easily.

Step 4: wait before polling

Add a Wait node after job creation so your workflow does not hit the API in a tight loop. 30 to 60 seconds is a good starting interval for most jobs. After the wait, call:

GET https://api.brezelscraper.com/api/v1/jobs/{{ $json.jobId }}

The response looks like this:

{
  "id": "d8d8a24e-cef2-4b02-8396-abc290b6f299",
  "name": "Berlin cafes",
  "status": "running",
  "data": { ... },
  "result_count": 0,
  "created_at": "2026-04-10T12:00:00Z"
}

Check the status field and branch accordingly:

pending, running, or aborting: wait again, then poll again
completed: continue to results
failed or cancelled: stop the workflow or route to your error handling path

You can also check result_count before fetching results. If it is 0, there is nothing to download.

Step 5: fetch results

Once the status is completed, fetch structured results:

GET https://api.brezelscraper.com/api/v1/jobs/{{ $json.jobId }}/results

Use this when you want JSON data inside n8n. If you want the CSV file instead:

GET https://api.brezelscraper.com/api/v1/jobs/{{ $json.jobId }}/download

Cancelling a job

To stop a running job from n8n (for example on a timeout), send:

POST https://api.brezelscraper.com/api/v1/jobs/{{ $json.jobId }}/cancel

The job status will move to aborting and then to cancelled.

Optional: trigger n8n from BrezelScraper webhooks

Instead of polling, you can have BrezelScraper notify n8n when a job finishes.

Set up the webhook

In n8n, add a Webhook node and copy its Production URL
In BrezelScraper, open Dashboard > Integrations
Create a webhook and paste the n8n production URL
Copy the signing secret and store it securely (you will only see it once)

BrezelScraper sends a POST request to your webhook URL when a job reaches a terminal state.

Webhook payload

{
  "event_type": "job.completed",
  "job_id": "d8d8a24e-cef2-4b02-8396-abc290b6f299",
  "job_name": "Berlin cafes",
  "status": "completed",
  "result_count": 87,
  "created_at": "2026-04-10T12:00:00Z",
  "ended_at": "2026-04-10T12:05:30Z"
}

Possible event_type values: job.completed, job.failed, job.cancelled. The payload contains metadata only. Fetch results through the API after receiving the webhook.

Verify the signature

Each delivery includes an X-Webhook-Signature header with an HMAC-SHA256 signature of the request body. In your n8n Code node:

const crypto = require('crypto');
const sigHeader = $input.first().headers['x-webhook-signature'];
const parts = Object.fromEntries(sigHeader.split(',').map(p => p.split('=')));
const timestamp = parts.t;
const signature = parts.sha256;

const expected = crypto
  .createHmac('sha256', 'your_signing_secret')
  .update(timestamp + '.' + $input.first().body)
  .digest('hex');
const valid = crypto.timingSafeEqual(
  Buffer.from(signature),
  Buffer.from(expected)
);

Delivery and retries

BrezelScraper retries failed deliveries up to 5 times with exponential backoff. Each delivery has a unique X-Webhook-ID header you can use for deduplication. The timestamp in the signature header is cryptographically signed, so reject deliveries where t is more than 5 minutes old.

Error handling

The API returns standard HTTP status codes. Handle these in your n8n workflow with an IF node or error branch:

Code	Meaning	What to do
`201`	Job created	Continue
`200`	Request succeeded (poll, results, download)	Continue
`402`	Insufficient credits	Stop and alert the user
`404`	Job not found or not owned by you	Check the job ID
`422`	Invalid request body	Check field values and types
`429`	Rate limit hit	Wait and retry after the number of seconds in the `Retry-After` header

Polling too fast is the most common cause of 429 errors. Space your Wait nodes at least 10 seconds apart.

Good production habits

Add an Idempotency-Key header on POST /api/v1/jobs if your workflow may retry on failure
Handle failed and cancelled jobs explicitly instead of looping forever
Keep the job ID in one field throughout the workflow so every node can reference it

Getting started

Using BrezelScraper

Before you start

Workflow overview

Step 1: create an API key

Step 2: create a job with an HTTP Request node

Step 3: keep the job ID in your workflow

Step 4: wait before polling

Step 5: fetch results

Cancelling a job

Optional: trigger n8n from BrezelScraper webhooks

Set up the webhook

Webhook payload

Verify the signature

Delivery and retries

Error handling

Good production habits

Official n8n docs

​Before you start

​Workflow overview

​Step 1: create an API key

​Step 2: create a job with an HTTP Request node

​Step 3: keep the job ID in your workflow

​Step 4: wait before polling

​Step 5: fetch results

​Cancelling a job

​Optional: trigger n8n from BrezelScraper webhooks

​Set up the webhook

​Webhook payload

​Verify the signature

​Delivery and retries

​Error handling

​Good production habits

​Related pages

​Official n8n docs

Before you start

Workflow overview

Step 1: create an API key

Step 2: create a job with an HTTP Request node

Step 3: keep the job ID in your workflow

Step 4: wait before polling

Step 5: fetch results

Cancelling a job

Optional: trigger n8n from BrezelScraper webhooks

Set up the webhook

Webhook payload

Verify the signature

Delivery and retries

Error handling

Good production habits

Related pages

Official n8n docs