Webhooks

Webhooks push article data from Grandranker to your own endpoint the moment something happens, without requiring polling. This is how the Custom API integration delivers articles to headless sites, and it also works alongside any other integration.

You manage webhooks per website at https://app.grandranker.com/webhooks (admin or owner role required, with a website selected).

Events

Every webhook is subscribed to all available events:

Event	Fires when
Article Published	An article is published to your website
Article Updated	A published article is edited and re-published
Article Deleted	An article is deleted
Article Generated	A new article finishes generating
AI Overview Alert	An AI visibility check raises a warning or critical alert
AI Overview Snapshot Complete	An AI visibility snapshot run finishes

Creating a webhook

1. Open Webhooks and click Add Webhook (or Create Your First Webhook).
2. Enter a Name (e.g. "My Website") and the Endpoint URL where Grandranker should POST, e.g. https://yourwebsite.com/api/webhook.
3. After creation, a dialog shows your Access Token. Copy it now. Your endpoint should validate the Authorization: Bearer <token> header on incoming requests. You can view it again later via View Access Token in the row menu.
4. Click Send Test to receive a sample payload and confirm your endpoint responds.

Payload format

Requests are JSON POSTs with Content-Type: application/json and a User-Agent: Grandranker-Webhook/1.0 header. The body contains:

• event_type: e.g. publish_articles, article_generated, update_article, delete_article
• timestamp: ISO 8601
• data.articles[]: the full article objects including id, title, meta_title, meta_description, slug, content_markdown, content_html, publish_date, category, tags, faqs, image_url, author_name, read_time, word_count, language_code, json_ld_schema, and more

The Webhook Payload Format card at the bottom of the Webhooks page shows a full sample payload and the endpoint requirements: accept POST JSON, validate the bearer token, and return a 2xx status code.

Delivery, retries and failures

• Any 2xx response counts as delivered. Anything else (including timeouts at 30 seconds by default) counts as a failure.
• Failed deliveries are retried automatically up to 3 times with exponential backoff (1 minute, then 5, then 15).
• The Delivery History card lists your 50 most recent deliveries with event, endpoint, status, response code and time. Expand a row to inspect the request payload, response body and error, or to retry a failed delivery manually.
• If 5 consecutive deliveries fail, the webhook is automatically disabled to protect your endpoint. Fix the issue, then flip the Status toggle back on.

Managing webhooks

Each row has a Status toggle (enable/disable) and a menu with Send Test, Edit (name and URL), View Access Token, and Delete. A health badge shows at a glance whether recent deliveries are succeeding.

Webhooks can also be managed programmatically via the REST API with the webhooks:read / webhooks:write scopes.

Questions? Contact us at [email protected].