SeoPrimo in n8n.

The most direct way: every endpoint of the REST API is an HTTP call.

Importing endpoints

n8n does not read an OpenAPI file by itself. The quick way is the Import cURL button of the HTTP Request node: paste the curl call of an endpoint (the interactive documentation shows it with "Try it out", and you will find it in the examples of the API guide) and the node fills in method, address and body. Then pick the credential. The /api/v1/openapi.json file is the full contract, useful if you want to generate nodes or clients with an OpenAPI generator.

Waiting for a long job

The quick audit is followed with a loop: Wait, then GET /sites/{id}/audits and look for the audit by id, then an IF that goes back to Wait until the status is done or failed. Long jobs (full audit, rank check) are followed the same way with GET /runs/{id}. The first downloadable workflow does exactly this, with a limit of about 20 minutes.

If your n8n is reachable from the internet, webhooks avoid the loop: SeoPrimo tells you when the job is done.

To react to an event (Score changed, credits low, report ready) without polling the API. The SeoPrimo webhook signs every delivery: your workflow must check the signature on the raw body.

1. Webhook node: Method POST, a Path of your choice, Respond = "Using 'Respond to Webhook' Node". In Options turn Raw Body on.
2. Code node with the code below: it recomputes the HMAC on the raw body and returns valid.
3. IF node on valid: the true branch answers 200 and continues, the false branch answers 401 with Respond to Webhook.
4. On the n8n server set the environment variable NODE_FUNCTION_ALLOW_BUILTIN=crypto: the Code node can load the crypto module only if it is allowed.
5. Activate the workflow, copy the Webhook node's Production URL and add it in Integrations, Webhooks choosing the events. The whsec_… secret is shown only once: paste it into the Code node.
6. Press "Send test" on the webhook: a test event arrives.

// Verify X-SeoPrimo-Signature on the RAW body (Webhook node: option "Raw Body" ON).
// Needs the env var NODE_FUNCTION_ALLOW_BUILTIN=crypto on the n8n server (or '*').
const crypto = require('crypto');

// Paste the endpoint secret (whsec_...) here, or expose it as the env var SEOPRIMO_WEBHOOK_SECRET.
let secret = 'whsec_REPLACE_WITH_YOUR_SECRET';
try { if ($env.SEOPRIMO_WEBHOOK_SECRET) secret = $env.SEOPRIMO_WEBHOOK_SECRET; } catch (e) { /* env access blocked */ }
const TOLERANCE_SECONDS = 300;

const item = $input.first();
const header = String(item.json.headers['x-seoprimo-signature'] || '');
const raw = await this.helpers.getBinaryDataBuffer(0, 'data'); // the bytes exactly as received

let valid = false;
try {
  const parts = Object.fromEntries(header.split(',').map((p) => p.split('=', 2)));
  const t = parseInt(parts.t, 10);
  const received = String(parts.v1 || '');
  const expected = crypto.createHmac('sha256', secret).update(`${t}.`).update(raw).digest('hex');
  const fresh = Math.abs(Date.now() / 1000 - t) <= TOLERANCE_SECONDS;
  valid = fresh
    && received.length === expected.length
    && crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(received));
} catch (e) {
  valid = false;
}

const event = valid ? JSON.parse(raw.toString('utf8')) : {};
return [{ json: { valid, id: event.id, type: event.type, created: event.created, data: event.data || {} } }];

The whsec_REPLACE_WITH_YOUR_SECRET value is a placeholder: replace it with your endpoint's secret or read it from $env.SEOPRIMO_WEBHOOK_SECRET. The code is the same as the Node verification in the webhook guide.