---
title: "Notifications and webhooks"
description: "What SureBright can tell your systems when something happens, the mechanism for each kind of event today, and what it does not push."
---

This page answers one question: when something happens in your protection programme, how do your own systems find out? Some events are pushed to you, some you read from an API response, and some you have to poll for.

SureBright does not send contract or claim events to a merchant endpoint today. If you need contract or claim changes pushed to your systems, ask your SureBright contact.

## Find the mechanism

| You want to know when | Mechanism today | Push or pull |
|---|---|---|
| A contract was created for an order you sent by API | The response to [Create Contracts for Order](/api-reference/endpoint/order/create-contract) lists every `contractId` in `contractList` | Pull (same request) |
| A contract on one of your orders was cancelled or changed | Poll [Get Contracts for Order](/api-reference/endpoint/order/get-contracts) for that order | Pull |
| A contract is on hold or needs something from you | The merchant portal. See [Why a contract is on hold](/contracts/holds) and [Order Resolution](/merchant-portal/order-resolution), which is available on request | Pull (portal) |
| Contracts were sold over a period | **Download** on [Sales](/merchant-portal/sales) gives a CSV for a date range | Pull (portal) |
| A claim was filed, approved, declined or settled | No API and no webhook. The customer is emailed at each stage; see [Claim communications](/claims/communications). Where your team sees claims is covered in [Merchant adjudication](/claims/merchant-adjudication) | Pull (portal) |
| A shopper selects or removes a plan on your storefront | `window.SureBright.onSelectionChange` and the `sb-widget-event` DOM events from the storefront SDK. See the [JavaScript API Reference](/frontend-widget-integration/frontend-widget-kit/javascript-injection) | Push (in the browser) |
| A cart is abandoned, an offer is prepared or sent, or a cart is recovered | The abandoned-cart **Webhook** connected tool, or Klaviyo or Omnisend events. See [Channels and connected tools](/abandoned-cart-guide/channels) | Push |
| An order is eligible for a post-purchase offer, or a plan was bought from one | Klaviyo events **SureBright: Eligible Order** and **SureBright: Policy Purchased**. See [Email integrations](/klaviyo-integration/integration-guide) | Push (into Klaviyo) |
| The customer was emailed about their plan | Not pushed to you. The list of emails and when each is sent is on [Emails your customers receive](/customer-emails/overview) | None |

## Polling for contract changes

[Get Contracts for Order](/api-reference/endpoint/order/get-contracts) takes one `storeId` and one `partnerOrderId` per call and returns the order with its active contracts. Cancelled contracts are left out, so a `contractId` you stored that no longer appears in `data.contracts` has been cancelled.

There is no endpoint that lists every contract changed since a point in time. In practice:

- Store the `contractId` values from the create response against your order lines.
- Re-read an order when something happens to it on your side, for example a refund or an edit, rather than on a timer across all orders.
- If you do run a periodic check, keep it to recent orders and a modest request rate. See [Limits, idempotency and versioning](/api-reference/limits-and-versioning).

## The abandoned-cart Webhook

This is the one place where SureBright posts events to a web address you own. It is set up in the merchant portal under **Abandoned Cart**, then **Messages → Connected tools**, on stores where Abandoned Cart is switched on. It carries abandoned-cart events only, not contract or claim events.

| Aspect | Behaviour |
|---|---|
| Endpoint | An `https` URL. Connecting sends a signed ping and needs a `2xx` answer. Redirects are not followed |
| Request | One JSON `POST` per event with `id`, `event`, `event_name`, `occurred_at`, `shop` and `data` |
| Headers | `X-SureBright-Signature`, `X-SureBright-Event`, `X-SureBright-Delivery`, `X-SureBright-Timestamp` |
| Signature | `sha256=` followed by the hex HMAC-SHA256 of the raw request body, keyed with the signing secret shown once when you connect |
| Success | Any `2xx` answer within 10 seconds |
| Retries | A failed delivery is tried up to 3 times in all, at least 10 minutes apart, within 24 hours. After that the event is not sent again |

Compute the HMAC over the body exactly as received, before any JSON parsing, and compare it with the header. Use the `X-SureBright-Delivery` value to ignore a delivery you have already processed. The event names and what each one carries are listed on [Channels and connected tools](/abandoned-cart-guide/channels#events-your-tool-receives); the full field list is in the **Event catalog** on the Connected tools screen.

## Webhooks SureBright receives

When your store runs on a supported platform, SureBright subscribes to that platform's order, refund, fulfilment and product events so that contracts follow your orders. Those are inbound to SureBright and you never call them. They are listed on [Platform webhooks SureBright receives](/api-reference/endpoint/webhooks/platform-receivers), which is useful when you audit the webhooks on your store.

A custom integration has no such subscription. You tell SureBright about a new, changed or cancelled order yourself, with the calls in [Integrate with the API](/api-reference/integration-tutorial).

## Related

<CardGroup cols={2}>
  <Card title="Integrate with the API" href="/api-reference/integration-tutorial" icon="rocket">
    The calls that create, update and look up contracts.
  </Card>
  <Card title="Channels and connected tools" href="/abandoned-cart-guide/channels" icon="plug">
    The Webhook, Klaviyo and Omnisend for abandoned-cart events.
  </Card>
  <Card title="JavaScript API Reference" href="/frontend-widget-integration/frontend-widget-kit/javascript-injection" icon="code">
    Storefront callbacks and DOM events.
  </Card>
  <Card title="Emails your customers receive" href="/customer-emails/overview" icon="file-text">
    What SureBright sends to customers and when.
  </Card>
</CardGroup>
