Automate with the API and webhooks

Everything so far has happened in SEODojo's screens. The API and webhooks let your own code take part: a headless site reading its articles, an internal tool sending drafts in, a build hook that deploys when an article is published.

This lesson is for developers. If that's not you, lesson 8.5 does much of the same through an AI assistant, without writing code.

Step 1: Create an API key

On Publish Queue, under API access → API keys, click New key. You can limit a key to one site, and you should. A key for ieltsbandlift.com's blog has no reason to see seodojo.app's articles.

The key is shown once. SEODojo stores only a hash of it, so copy it straight into your secrets manager or environment variables. Keys start with sdk_, so secret scanners can recognise them if one ever leaks into code. You can replace a key with a new one, and the old one keeps working for a short while so nothing breaks while you switch.

Generating a key needs Pro. The REST API itself is on Scale. (The MCP server, lesson 8.5, is on Pro.)

Step 2: Make a request

The API lives at https://api.seodojo.app/v1. Send the key as a bearer token:

curl https://api.seodojo.app/v1/articles?limit=5 \
  -H "Authorization: Bearer $SEODOJO_API_KEY"

What's there:

site takes one of your domains. If the key is limited to a site, that's the only site it can use.

Sending a draft in:

curl -X POST https://api.seodojo.app/v1/queue \
  -H "Authorization: Bearer $SEODOJO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title": "IELTS Speaking Part 3: Sample Questions", "content": "## Introduction\n...", "keyword": "ielts speaking part 3", "site": "ieltsbandlift.com"}'

It lands in the Publish Queue as pending review, the same as a draft from the Editor. Nothing published through the API skips review: a person still approves it (lesson 4.2). Leave out description and a meta description is written for you.

Step 3: Add a webhook destination

A webhook is SEODojo calling your URL. On the Publish Queue, add a Webhook destination (lesson 4.1) with:

• Webhook URL: your endpoint. A test ping is sent when you connect.
• Signing secret (optional, but use one): every request then carries X-SeoDojo-Signature: sha256=<HMAC-SHA256 of the body>, so your endpoint can prove it came from SEODojo.

Each published article is then POSTed to your URL as JSON:

{ "event": "article.publish", "title": "…", "description": "…", "slug": "ielts-speaking-practice", "markdown": "…", "html": "…" }

The request also carries an X-SeoDojo-Event header. Any 2xx response counts as success. If you reply with JSON containing id and/or url, SEODojo records them as the post's id and live link.

That makes the webhook a universal destination. Point it at a Zapier, Make or n8n hook to fill a Framer CMS or anything else they connect to, at a static-site build hook, or at your own endpoint.

Two things to build into your endpoint:

• Verify the signature. Compute the HMAC of the raw request body with your secret and compare it to the header, then reject anything that doesn't match.
• Make it safe to repeat. Use the slug to update rather than duplicate, so publishing the same article twice doesn't create two posts.

Tip: The webhook and GET /v1/articles both deal in published articles. To see what's waiting in the queue, the MCP server's list_publish_queue tool can tell you (lesson 8.5).

Done when

• You have an API key, limited to one site, stored as a secret
• A GET /v1/articles request works
• You've queued a test draft through the API, and seen it waiting for review
• A webhook destination with a signing secret, and an endpoint that verifies it