How to get website report notifications with a webhook

A website report webhook sends you one signed HTTPS request the moment IssueProbe stores a report. You do not need to poll the dashboard or watch an inbox. Each website can have one owner-configured webhook endpoint, and the same setup works for a human in the dashboard and for an authorized agent through the API.

This article explains what the webhook sends, how to verify each delivery, and how to build a receiver that survives downtime.

What a report webhook is

A webhook is an owner channel. It is not a visitor channel, and it is not email. IssueProbe sends email only for account authentication and owner authorization, so a webhook is the supported way to route new reports into your own tools: a chat notification, a ticket draft, or a private log.

Each website has at most one webhook endpoint. When the webhook is enabled, IssueProbe sends one report.received event for each stored report. The event fires in the same transaction that stores the report, and it also fires for a report that is stored without an investigation because the account has no monthly quota left. Storage never depends on the receiver: a failed delivery never blocks, changes, or deletes the report.

The event contains only safe facts:

• The website identifier and name.
• The report identifier and short reference.
• The report type, problem or suggestion.
• The report state at storage time.
• The received time.
• One dashboard link and one API link.

The event never contains the report description, the reporter contact email, browser evidence, screenshots, repository data, or investigation detail. When you need the full report, read it through the API link with an authorized credential or open the dashboard link as the owner.

Store the signing secret once

IssueProbe signs every request with the Standard Webhooks v1 scheme and one secret per endpoint. The secret appears exactly once, in the response when you create the webhook or rotate the secret. IssueProbe never shows it again, so move it into your receiver secret store immediately.

If you lose the secret, rotate it. The old secret stops working at once, and each later attempt, including a pending retry, uses the new secret. A receiver can reject requests in the short moment before it stores the new value, and those deliveries then receive their normal retries.

Each request carries three headers: webhook-id, webhook-timestamp, and webhook-signature. To verify a delivery:

1. Remove the whsec_ prefix from your stored secret and decode the rest from base64 to get the 32-byte key.
2. Build the signed content from the identifier, the timestamp, and the raw request body, joined with a period.
3. Calculate HMAC-SHA256 over that content with the key.
4. Compare the base64 result against the sent signature in constant time.

Read the raw body before any parsing, because a parsed and re-serialized body can have different bytes. Reject a timestamp that differs from your clock by more than five minutes. The agent documentation contains a complete receiver example that uses only Node.js built-in modules.

Answer fast and do slow work after

A 2xx response is a successful delivery. IssueProbe follows no redirect, so a 3xx response is a failure, and each attempt has a 15-second total limit. Return a 2xx status as soon as you have the event, and queue any slow work, such as a chat lookup or a ticket create, for after the response.

A failed attempt is retried on a fixed schedule:

• 1 minute after the first attempt.
• 5 minutes after the second.
• 30 minutes after the third.
• 2 hours after the fourth.
• 6 hours after the fifth.
• 12 hours after the sixth.
• The seventh failure marks the delivery as failed.

That gives a report.received delivery seven attempts over about 21 hours. IssueProbe does not guarantee event order, and a receiver can get one event more than once. Remove duplicates with the webhook-id value, which stays the same across retries of one event, and store the seen identifiers in durable storage with an expiry.

Ignore any event type you do not know and any field you do not expect, so a later addition cannot break your receiver.

Choose a compliant endpoint address

The endpoint URL must pass a strict schema before IssueProbe accepts it:

• The scheme is https and the port is empty or 443.
• The host is a public name with more than one label, not an IP address, not localhost, and not an internal suffix such as .local or .internal.
• The URL has no username, no password, and no fragment.

A query string is allowed, so a receiver token in the path or the query is a normal pattern. That makes the URL sensitive: IssueProbe returns it only to a human session or to an agent with read access for the same account, and it never appears in audit metadata, logs, or error messages.

Each attempt also checks the resolved addresses at connect time. A host that resolves to a non-public address fails the delivery, and a domain-name change between checks cannot bypass the rule.

Test before you rely on it

Send a webhook.test event from the dashboard or the API before you depend on the webhook. The test creates one delivery and sends it once during the request, with no retry, and it also works while the webhook is disabled. One website can send ten test events in a rolling hour.

Check the delivery history on the website page when something looks wrong. Each delivery shows its state, the attempt count, the last status code, and the next attempt time, so you can tell an unreachable receiver from a rejected signature. IssueProbe keeps delivery history for 30 days after a delivery reaches a terminal state.

Keep the boundary clear

A webhook tells you that a report exists. It does not investigate, reply, or decide. Follow the complete report lifecycle in what happens after a visitor sends a report, and read the exact request and response shapes in the API reference. If an agent manages the webhook for you, it needs write access for the website, and each action appears in your audit history. For the delivery security rules, see the security page.