Integration guide

Set up Rank Prompt webhooks

Stop polling. Rank Prompt calls your endpoint the moment a report or a scheduled run finishes, or fails, with a signed payload your server can trust.

Start free Explore the feature
Webhooks

Rank Prompt reads

  • Your endpoint’s response code

Rank Prompt sends

  • Event type and id
  • Report or run payload
  • HMAC signature
  • Delivery id
Rank Prompt

What it does

  • Sends report.completed, report.failed, schedule.run.completed and schedule.run.failed to your endpoint, per brand.
  • Signs every delivery with HMAC so you can prove it came from Rank Prompt.
  • Retries a failed delivery after 30 seconds, 2 minutes, 10 minutes, 1 hour, 6 hours and 24 hours.
  • Rotates the signing secret without downtime, and disables an endpoint after 20 failures in a row.
  • Also posts to Slack or Discord: pick the destination type and each event arrives as a message written for the channel.
  • Subscribes a brand endpoint to the article events too: article.published, article.updated and article.unpublished.
  • Sends a test delivery on demand, signed like a real one, with the answer and the time it took shown inline.

Before you start

Plan From Starter

  • A public HTTPS endpoint on your server that answers quickly with a 2xx code.
  • Somewhere to keep the signing secret, such as your secret manager.
  • Up to 5 active endpoints per brand.
Setup

Webhooks setup in 4 steps

  1. Step 1

    Open Developers, Webhooks

    In Rank Prompt, open Developers, choose the Webhooks tab and pick the brand.

    The Webhooks tab of the Developer API page, with the brand picker and the New webhook button.

  2. Step 2

    Add your endpoint

    Click New webhook, enter the https URL and choose the events it should receive.

  3. Step 3

    Keep the signing secret

    Copy the secret into your server. Each delivery carries X-RP-Signature with a timestamp and a v1 signature; recompute it over the raw body and compare.

  4. Step 4

    Handle deliveries

    Answer fast with a 2xx, then do the work. Use X-RP-Event-Id to ignore a retry you already processed.

Troubleshooting

Webhooks: errors and fixes

These are the messages the app shows, word for word, and what fixes each one.

  • Maximum of 5 active webhooks per brand reached.

    Disable or delete an endpoint you no longer use, or send several event types to one endpoint.

  • We disabled the webhook for Mercari (Signed JSON, b3f1c2d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d) after 20 consecutive failed deliveries. Fix the endpoint, then re-enable it to resume events.

    Make the endpoint answer a 2xx again, then re-enable it in the Webhooks tab. Deliveries that were dropped can be replayed from there.

All integrations

FAQ

Webhooks integration FAQs

Still have questions? Contact our team

Which events can I subscribe to?

report.completed, report.failed, schedule.run.completed and schedule.run.failed, plus article.published, article.updated and article.unpublished, per brand. On Agency Plus the account owner can also set up account-level endpoints for lead.created, lead.report_ready, lead.report_failed and lead.claimed, in Developers, Webhooks, under Account (/developers?tab=webhooks&scope=account).

What happens if my endpoint is down?

The delivery is retried six times over about a day: after 30 seconds, 2 minutes, 10 minutes, 1 hour, 6 hours and 24 hours. After 20 consecutive failures the endpoint is disabled until you turn it back on.

How do I verify a delivery?

Recompute the HMAC of the timestamp and the raw body with your signing secret and compare it with the signature in X-RP-Signature. The developer docs have code for it.

Which plan do I need?

Webhooks start on Starter at $49 a month, or come with a standalone API plan.

Can I send events to Slack or Discord?

Yes. Choose Slack or Discord as the destination type and paste the channel’s incoming webhook URL: each event arrives as a message for that channel, in the owner’s language.

How do I test an endpoint?

Click Send test on the endpoint. The test is signed like a real delivery, carries test: true, never counts toward the auto-disable, and shows your endpoint’s answer and time. A Replay from the delivery log sends a new delivery with a new delivery id and the same event id and body as the first one.

Is this how I publish articles to Zapier or Make?

No, that is a webhook destination: it sends the whole article, signed, when you publish, and records where it went live. The webhooks here tell your tools that something happened.

Up and running in a few minutes

Create a free account, follow the steps above and see what the connection adds to your AI visibility.

Start free View pricing