Set up and receive notification webhooks

Webhooks send Informed notifications directly to your application as signed HTTPS POST requests. Use them to connect notifications to your own workflows, dashboards, or integrations.

You choose which notifications to receive through your notification subscriptions. Adding an endpoint alone does not subscribe it to events. Notifications must be enabled for your account before you can access these controls.

You need a receiver with a public HTTPS URL and a valid TLS certificate, such as https://notifications.example.com/webhook. It must accept POST requests, preserve the raw request body for signature verification, and respond within 10 seconds. Use a URL without embedded credentials, fragments (#...), or whitespace.

Webhook endpoints are shared by everyone in your Informed account. Account members can manage the same endpoints and select verified endpoints for their own subscriptions. Store signing secrets in private server configuration or a secret manager.

Informed signs challenges, tests, and notification deliveries using the same method. These headers accompany each request:

For each configured secret, calculate:

Clicking Verify sends an envelope like this. Example IDs, timestamps, and values throughout this guide are illustrative.

First authenticate the request. Then respond with HTTP 200, Content-Type: application/json, and:

Echo payload.challenge exactly, with a single challenge string property at the root of your response. Do not wrap it in payload or data, return just the string, or return the signing secret. Any 2xx status can succeed, but an empty response cannot verify the endpoint. Keep the response uncompressed, within 4 KiB, and within the 10-second request deadline.

Verification and test requests are each sent once, without automatic retries. After correcting a failure, click Verify or Test again. These requests do not appear in Latest Delivery Status.

All webhook bodies use the following envelope. Envelope field names use snake_case; individual notification payload fields retain the capitalization shown in the payload reference.

All event types related to listings in Informed (e.g. informed.listing.saved_view_change and informed.listing.order) include these fields inside payload:

Listing details come from the data available when the event is generated. Null-valued fields are omitted, so string fields and optional amounts can be absent when unavailable. Date-time examples use UTC (Z); parse date-time strings with an appropriate date-time library.

An event describes one listing's change in membership of one saved view. In addition to the shared fields, the payload includes:

EventSource is currently ListingDataInserted, ListingDataUpdated, ViewInserted, or ViewUpdated. A change to a view's definition can therefore generate membership notifications as well as a change to a listing.

For an exit notification, EnteredView is false and ExitedView is true. Route using these booleans and ViewKey, rather than the view's display name.

New and cancelled order notifications use the same event type and payload structure. Each event concerns an order line item associated with a listing and a matching saved view. EventSource is orders.

The following is a complete example payload; it is placed inside the envelope with event_type: "informed.listing.order":

For a cancelled order, OrderStatus is Cancelled; IsNewOrder may be false. Do not interpret every IsNewOrder: false event as a cancellation.

Order metadata contains informed_saved_view_url, informed_listing_url (a link to the listing in Informed), and amazon_listing_url (the marketplace listing link). Saved-view changes contain the first and last of these. The amazon_listing_url field name is retained even when the link points to a different supported marketplace.

The same listing or order may match more than one saved view or subscription. Such deliveries can have different UUIDs and should not be discarded as retries solely because their order or listing IDs match.

Tests use the common envelope with null notification_id, delivery_id, and metadata, a fresh idempotency_key, and this payload:

After authenticating, return any 2xx response, such as 204 No Content. No challenge echo is required. A successful test confirms your receiver accepted the test request; trigger a matching subscription event to validate your notification-processing workflow.

For notification deliveries, return a 2xx status after durable acceptance. An empty 204 No Content response is sufficient; response bodies are ignored. Complete the response within 10 seconds, and process longer-running work from your durable queue.

Retryable deliveries stop after five failed attempts in total. Retries use exponential backoff; actual send times depend on scheduling. Check Next retry in the delivery status view instead of relying on a fixed schedule. Challenges and explicit tests are excluded from automatic retries.

Delivery is at least once: your receiver can receive the same delivery again even after it returned 2xx, for example if the acknowledgment could not be recorded. Deduplicate by the top-level idempotency_key, and return 2xx for an already accepted delivery. The key and logical event content remain the same across retries; signing timestamps and signatures are refreshed. Do not use the signature, timestamp, or source correlation key as your deduplication key. Do not assume deliveries arrive in event-time order.

In Notification Settings → Delivery Channels, click the webhook row's View delivery status list icon to open Latest Delivery Status. Use Refresh to check the status, failed attempts, latest HTTP response or error code, and next retry time.

sent means delivery succeeded; dead means it has stopped retrying. pending and failed can be waiting for a send or retry; processing or sending indicates work in progress. Failed attempts counts failures, so a delivery that succeeds on its first attempt shows 0.

Verification and test outcomes appear on the webhook row instead of this list. The status view shows current delivery outcomes, without a full attempt timeline or receiver response bodies. There is no manual resend action.

Rotate a secret: Click Rotate on the webhook row. Copy and save the new secret immediately, then install it on your receiver before the previous secret's displayed expiry. The expiry is shown in your local time zone. During the overlap period, requests can carry signatures for both secrets; accept either valid signature. To cover requests already in flight, you can configure both secrets on your receiver (WEBHOOK_SECRET and WEBHOOK_PREVIOUS_SECRET in the example), then remove the previous secret after expiry. Rotation preserves verification. Another rotation can be blocked while the overlap period is active.

Recover a lost secret: The original value cannot be displayed again. Rotate and save a new secret. If a rotation is already in its overlap period, wait until another rotation is allowed or create and verify a replacement endpoint. If a create or rotate request reports an unknown outcome, refresh the channel state before trying again; retrying cannot recover a secret that was already issued.

Disable a channel: Use its enabled toggle. A disabled channel can still be selected in subscriptions, but selection does not enable it. Manually disabling a shared webhook affects all account members and can permanently reject queued deliveries, so it is not a pause-and-replay mechanism.

Recover from automatic disablement: Informed automatically disables a webhook after five consecutive distinct deliveries end in qualifying receiver, network, or destination failures. This counts completed failed deliveries, rather than five retry attempts on one delivery. Previously queued work can continue after automatic disablement, but new deliveries stop. Fix the receiver, use Test, inspect delivery status, then explicitly re-enable the channel. Tests and verification do not reset the failure streak or re-enable the channel.

Change a URL or delete an endpoint: The URL cannot be edited. Create and verify a replacement, update the affected subscriptions, and allow outstanding deliveries to finish before deleting the old endpoint. References from other account members, disabled subscriptions, or queued deliveries can block deletion.

Confirm that the URL is publicly reachable over HTTPS, the receiver is running, and the complete secret is installed. Inspect the result on the webhook row, then click Verify after fixing the issue.

Return JSON with the exact payload.challenge string in a root challenge field. Check for an empty body, a nested field, duplicate challenge properties, or a response rewritten by middleware.

Return a small, uncompressed JSON challenge response within 4 KiB.

Check the complete whsec_ value, raw body bytes, signing header names, server clock, and support for either comma-separated signature during rotation.

Check DNS, firewall rules, receiver availability, and the 10-second deadline.

Check the certificate and URL. The hostname must resolve only to allowed public addresses; use the final destination URL directly.

It must be verified and belong to the current account. Refresh settings after successful verification.

system.test is a separate connectivity check. Enable and select the channel on a matching subscription, then trigger an actual event.

Check the subscription rules, subscription enabled state, channel enabled state, and latest delivery outcomes. An automatically disabled channel must be re-enabled after recovery.

This example is a starting point for connecting Informed to your application. It uses only Node.js built-in modules and can be adapted to different hosting environments.

As written, the receiver listens at 127.0.0.1:8080. This is a local address that only the computer running the receiver can reach. This example assumes that an HTTPS reverse proxy runs on that same server. A reverse proxy is the public-facing service that accepts the secure connection and passes the request to your receiver:

The developer or hosting provider needs to configure that public URL, its TLS certificate, and forwarding to the receiver. The proxy must preserve /webhook, the signing headers, and the exact request body bytes so signature verification succeeds.

The example handles verification and tests immediately. It does not yet save notifications or carry out your workflow. Complete the integration steps after the code before enabling notification subscriptions. Until then, ordinary notification requests receive HTTP 503 so they are not incorrectly acknowledged as saved. These failed deliveries are still subject to Informed's retry limit.

The 1 MiB incoming-body limit is an example receiver limit, not an Informed payload-size guarantee.

The function named acceptDeliveryOnce is where you connect the receiver to your system. The example deliberately leaves this function unfinished because the action to take and the place to save work depend on your application. A successful Verify or Test confirms connectivity and authentication; it does not confirm that this connection to your workflow is complete.

Complete these steps before enabling notification subscriptions:

Treat system.test as a connectivity check, without creating orders or running your normal notification workflow. When adding event handlers, allow additional JSON fields and safely acknowledge event types you intentionally ignore after authentication.

The example uses a single server with a reverse proxy on the same host. If your application follows a different receiver architecture that:

you must adapt the listener and request-body capture shown above to that platform. For example, a proxy in a separate container cannot reach this receiver through its own 127.0.0.1. The public HTTPS requirement, signature checks, and challenge response stay the same.