Custom API

No CMS? Custom stack? You can receive every article Grandranker produces on your own HTTP endpoint. Create a webhook, and Grandranker sends articles to your URL as JSON POST requests with Bearer token authentication. Your app decides what to do with them: store them, render them, forward them.

How to Connect

1. In Grandranker, open Webhooks (also reachable from Integrations: the "Webhooks: Connect to any service via HTTP" option).
2. Click Add Webhook.
3. In the Create Webhook dialog, enter a Name and the URL of your endpoint. Articles will be sent via POST request with Bearer token authentication.
4. Click Create Webhook. Grandranker generates a secret token for this webhook. Configure your endpoint to validate the Authorization: Bearer <token> header against it. You can reveal the secret again later from the webhook's row.
5. Use the Test action on the webhook to send a sample request. If your endpoint responds with a 2xx status, you're connected.

Webhooks can fire on these events: article.published, article.updated, article.deleted, article.generated, plus AI-visibility events (ai_overview.alert, ai_overview.snapshot_complete).

Publishing & Verifying

When an article publishes, Grandranker POSTs a JSON payload to your URL containing the article data: title, content, image URL and related metadata. Your endpoint should:

1. Return a 2xx response quickly.
2. Validate the Authorization: Bearer <token> header before trusting the payload. Webhooks can also be configured with HMAC signature authentication instead. In that mode each request carries an X-Webhook-Signature header your server verifies against the secret.

To verify end to end, publish one article and check the Delivery History section on the Webhooks page. Every delivery is logged with its event type and response. Failed deliveries have a Retry Delivery button. The test endpoint's diagnostics also spell out common fixes when a delivery fails.

If you prefer to pull rather than be pushed to, Grandranker also has a REST API with token authentication. See REST API & Tokens. For a deeper reference on payloads, events and delivery behavior, see Webhooks.

Troubleshooting

Test delivery fails with an authentication error (401/403)

Your endpoint rejected the request. It must accept and validate the Authorization: Bearer <token> header Grandranker sends. If your endpoint uses a different auth method, adjust it to accept Bearer tokens. Or reveal the webhook secret in Grandranker and check it matches what your server expects.

Deliveries time out or never arrive

Check that the URL is publicly reachable over HTTPS (not localhost or an internal hostname). Make sure no firewall or WAF blocks external POST requests. Respond within a few seconds. Do heavy processing after returning 2xx, not before.

A delivery failed once. Is the article lost?

No. Open Delivery History and expand the failed delivery to inspect the request and response. Fix your endpoint, then click Retry Delivery.

Questions? Contact us at [email protected].