Webhooks

Where every points movement is sent, and a way to check a receiver. Managing webhooks needs write_webhooks, and a key for an AI assistant or a test key can never do it: an endpoint is a standing channel out of the account. Each event is POSTed as JSON to every enabled endpoint subscribed to its type, signed the Standard Webhooks way: webhook-id (the same on every retry, and the thing to de-duplicate on), webhook-timestamp (unix seconds of this attempt; reject one more than 5 minutes from your clock), and webhook-signature: v1,<base64 HMAC-SHA256> over <webhook-id>.<webhook-timestamp>.<body>, keyed by the base64 after whsec_ in the endpoint's secret, decoded to bytes. Verify the raw body, before parsing it. Answer 2xx within 15 seconds; anything else, a redirect, or no answer is a failure, and the event is sent again after 5 seconds, 5 minutes, 30 minutes, then 2, 5, 10, 14, 20 and 24 hours (each ±10%) — ten attempts over about 75 hours — with the same id and the same bytes. Events can arrive out of order: data.ledger_entry_id and data.created_at order them. An endpoint that has failed 10 deliveries in a row AND been failing for at least 24 hours is disabled: nothing more is sent to it, what was waiting is abandoned, webhook.disabled is written to the audit log, and GET /webhooks shows status: disabled. Delete it and create it again once the receiver works. An endpoint receives the events recorded after it was created.

Part of the API reference, version 2026-10. Every address below starts with the base address:

https://app.matrixrewards.co.uk/api/2026-10

The webhook endpoints on this account, and why any stopped

GET /webhooks — the full address is https://app.matrixrewards.co.uk/api/2026-10/webhooks.

Needs: the write_webhooks permission (in the app: “Send every change to members’ points, by member key, to a web address the key chooses (webhooks). Not for an assistant key”).

Deleted endpoints are not listed. Needs write_webhooks, because an endpoint's URL can carry the merchant's own token. Written to the audit log (webhooks.list) before it answers.

The answer

The endpoints.

Headers on the answer: Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset. What each header means.

Example

curl "https://app.matrixrewards.co.uk/api/2026-10/webhooks" \
  -H "Authorization: Bearer $MATRIX_API_KEY"

The answer:

{
  "data": [
    {
      "object": "webhook_endpoint",
      "id": "we_Q3mN8xR2vT6pL9wK4sJ7hF1d",
      "url": "https://hooks.example.com/matrix-rewards",
      "event_types": [
        "points.earned",
        "points.adjusted"
      ],
      "description": "Our CRM",
      "status": "enabled",
      "created_at": "2026-09-16T10:00:00.000Z",
      "disabled_at": null,
      "disabled_reason": null,
      "consecutive_failures": 0,
      "failing_since": null,
      "last_success_at": null,
      "last_failure_at": null
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Other answers

Send points movements to an https endpoint

POST /webhooks — the full address is https://app.matrixrewards.co.uk/api/2026-10/webhooks.

Needs: the write_webhooks permission (in the app: “Send every change to members’ points, by member key, to a web address the key chooses (webhooks). Not for an assistant key”).

Returns the endpoint and its signing secret, once. At most 5 enabled endpoints per account. The endpoint receives the events it subscribes to from the moment it is created — not before. Takes no Idempotency-Key: a stored answer would have to keep the secret, so a retry after a lost answer makes a second endpoint, which shows in the list and can be deleted. The endpoint and its audit entry (webhook.create, recording the URL's host only) are one transaction. The endpoint lasts as long as the key that created it: revoking that key, or ending it with the website seat that made it, deletes the endpoint too (webhook.delete, with the reason and the key's id); so does the signing out everywhere, or removal, of the website seat whose secret created it, whatever has become of the key since. A key's previous secret, still working while a rotation's grace lasts, cannot create one.

Request body

Sent as application/json.

The answer

The endpoint, with its secret.

Headers on the answer: Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset. What each header means.

Example

curl -X POST "https://app.matrixrewards.co.uk/api/2026-10/webhooks" \
  -H "Authorization: Bearer $MATRIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://hooks.example.com/matrix-rewards", "event_types": ["points.earned", "points.adjusted"], "description": "Our CRM"}'

The answer:

{
  "object": "webhook_endpoint",
  "id": "we_Q3mN8xR2vT6pL9wK4sJ7hF1d",
  "url": "https://hooks.example.com/matrix-rewards",
  "event_types": [
    "points.earned",
    "points.adjusted"
  ],
  "description": "Our CRM",
  "status": "enabled",
  "created_at": "2026-09-16T10:00:00.000Z",
  "disabled_at": null,
  "disabled_reason": null,
  "consecutive_failures": 0,
  "failing_since": null,
  "last_success_at": null,
  "last_failure_at": null,
  "secret": "whsec_EXAMPLE"
}

Other answers

Stop sending to an endpoint

DELETE /webhooks/{endpoint_id} — the full address is https://app.matrixrewards.co.uk/api/2026-10/webhooks/{endpoint_id}.

Needs: the write_webhooks permission (in the app: “Send every change to members’ points, by member key, to a web address the key chooses (webhooks). Not for an assistant key”).

Nothing more is sent to it, and events waiting to be sent are abandoned. The endpoint and its audit entry (webhook.delete) change together.

Parameters

The answer

Deleted.

Headers on the answer: Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset. What each header means.

Example

export ENDPOINT='<id of an endpoint from GET /webhooks>'
curl -X DELETE "https://app.matrixrewards.co.uk/api/2026-10/webhooks/$ENDPOINT" \
  -H "Authorization: Bearer $MATRIX_API_KEY"

The answer:

{
  "object": "webhook_endpoint_deleted",
  "id": "we_Q3mN8xR2vT6pL9wK4sJ7hF1d",
  "deleted": true,
  "abandoned_messages": 0
}

Other answers

Send one signed test event now

POST /webhooks/{endpoint_id}/test — the full address is https://app.matrixrewards.co.uk/api/2026-10/webhooks/{endpoint_id}/test.

Needs: the write_webhooks permission (in the app: “Send every change to members’ points, by member key, to a web address the key chooses (webhooks). Not for an assistant key”).

A webhook.test event, signed with the endpoint's secret and sent through the same checks as every delivery, answered with what happened. It is not stored or retried, and it never counts towards disabling the endpoint. Recorded in the audit log (webhook.test) before it is sent. Works on a disabled endpoint too, so a fixed receiver can be checked.

Parameters

The answer

What the receiver did. delivered is false for every failure; the request itself succeeded.

Headers on the answer: Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset. What each header means.

Example

export ENDPOINT='<id of an endpoint from GET /webhooks>'
curl -X POST "https://app.matrixrewards.co.uk/api/2026-10/webhooks/$ENDPOINT/test" \
  -H "Authorization: Bearer $MATRIX_API_KEY"

The answer:

{
  "object": "webhook_test",
  "id": "evt_test_4c0a9e7d21b3f58e6a0d9c12",
  "delivered": true,
  "status": 200,
  "error": null,
  "duration_ms": 212
}

Other answers

Events we send you

How each event is signed, sent, retried and ordered is at the start of this page. These are the events, and what each one holds.

Signing headers

points.earned — Points were earned: an order, a welcome or birthday bonus, a referral

What it holds

An example:

{
  "type": "points.earned",
  "timestamp": "2026-09-16T10:00:05.000Z",
  "data": {
    "ledger_entry_id": 4,
    "store_key": "example-store",
    "member_key": "mx_3f6c2a9e-8b41-4d7a-9e05-c1b7d24f6a18",
    "delta_points": 120,
    "rule_id": "base_earn",
    "source_type": "order",
    "created_at": "2026-09-16T10:00:00Z"
  }
}

Answer 2XX: Received. Anything else, a redirect, or no answer within 15 seconds is retried.

points.adjusted — The merchant changed a member's points: in the app, on the web page, or through this API

It holds the same fields as points.earned (WebhookEvent).

An example:

{
  "type": "points.adjusted",
  "timestamp": "2026-09-16T10:00:05.000Z",
  "data": {
    "ledger_entry_id": 2,
    "store_key": "example-store",
    "member_key": "mx_3f6c2a9e-8b41-4d7a-9e05-c1b7d24f6a18",
    "delta_points": 50,
    "rule_id": "admin_adjustment",
    "source_type": "admin_adjustment",
    "created_at": "2026-09-16T10:00:00.000Z",
    "adjustment_id": "goodwill-2026-09-16-0001"
  }
}

Answer 2XX: Received. Anything else, a redirect, or no answer within 15 seconds is retried.

points.redeemed — Points were spent on a reward, or taken back because a cancelled code had been spent

It holds the same fields as points.earned (WebhookEvent).

An example:

{
  "type": "points.redeemed",
  "timestamp": "2026-09-16T10:00:05.000Z",
  "data": {
    "ledger_entry_id": 5,
    "store_key": "example-store",
    "member_key": "mx_3f6c2a9e-8b41-4d7a-9e05-c1b7d24f6a18",
    "delta_points": -500,
    "rule_id": "redeem",
    "source_type": "redeem",
    "created_at": "2026-09-16T10:00:00Z"
  }
}

Answer 2XX: Received. Anything else, a redirect, or no answer within 15 seconds is retried.

points.returned — Points came back: a reward was cancelled, or could not be issued

It holds the same fields as points.earned (WebhookEvent).

An example:

{
  "type": "points.returned",
  "timestamp": "2026-09-16T10:00:05.000Z",
  "data": {
    "ledger_entry_id": 3,
    "store_key": "example-store",
    "member_key": "mx_3f6c2a9e-8b41-4d7a-9e05-c1b7d24f6a18",
    "delta_points": 500,
    "rule_id": "redeem_void",
    "source_type": "redeem_void",
    "created_at": "2026-09-16T10:00:00.000Z"
  }
}

Answer 2XX: Received. Anything else, a redirect, or no answer within 15 seconds is retried.

points.clawed_back — Points were taken back after a refund

It holds the same fields as points.earned (WebhookEvent).

An example:

{
  "type": "points.clawed_back",
  "timestamp": "2026-09-16T10:00:05.000Z",
  "data": {
    "ledger_entry_id": 6,
    "store_key": "example-store",
    "member_key": "mx_3f6c2a9e-8b41-4d7a-9e05-c1b7d24f6a18",
    "delta_points": -40,
    "rule_id": "refund",
    "source_type": "refund",
    "created_at": "2026-09-16T10:00:00Z"
  }
}

Answer 2XX: Received. Anything else, a redirect, or no answer within 15 seconds is retried.

points.expired — Points expired

It holds the same fields as points.earned (WebhookEvent).

An example:

{
  "type": "points.expired",
  "timestamp": "2026-09-16T10:00:05.000Z",
  "data": {
    "ledger_entry_id": 7,
    "store_key": "example-store",
    "member_key": "mx_3f6c2a9e-8b41-4d7a-9e05-c1b7d24f6a18",
    "delta_points": -80,
    "rule_id": "expiry",
    "source_type": "expiry",
    "created_at": "2026-09-16T10:00:00Z"
  }
}

Answer 2XX: Received. Anything else, a redirect, or no answer within 15 seconds is retried.

points.changed — Any other movement — today, points carried over when a shopper's data was erased at another store of the account

It holds the same fields as points.earned (WebhookEvent).

An example:

{
  "type": "points.changed",
  "timestamp": "2026-09-16T10:00:05.000Z",
  "data": {
    "ledger_entry_id": 8,
    "store_key": "example-store",
    "member_key": "mx_3f6c2a9e-8b41-4d7a-9e05-c1b7d24f6a18",
    "delta_points": -20,
    "rule_id": "erasure_carry",
    "source_type": "erasure_carry",
    "created_at": "2026-09-16T10:00:00Z"
  }
}

Answer 2XX: Received. Anything else, a redirect, or no answer within 15 seconds is retried.

programme.updated — The programme changed

Each event is POSTed as JSON to every enabled endpoint subscribed to its type, signed the Standard Webhooks way: webhook-id (the same on every retry, and the thing to de-duplicate on), webhook-timestamp (unix seconds of this attempt; reject one more than 5 minutes from your clock), and webhook-signature: v1,<base64 HMAC-SHA256> over <webhook-id>.<webhook-timestamp>.<body>, keyed by the base64 after whsec_ in the endpoint's secret, decoded to bytes. Verify the raw body, before parsing it. Answer 2xx within 15 seconds; anything else, a redirect, or no answer is a failure, and the event is sent again after 5 seconds, 5 minutes, 30 minutes, then 2, 5, 10, 14, 20 and 24 hours (each ±10%) — ten attempts over about 75 hours — with the same id and the same bytes. Events can arrive out of order: timestamp orders them. De-duplicate on webhook-id, never on data.version, which an expiry or look change leaves as it was. An endpoint that has failed 10 deliveries in a row AND been failing for at least 24 hours is disabled: nothing more is sent to it, what was waiting is abandoned, webhook.disabled is written to the audit log, and GET /webhooks shows status: disabled. Delete it and create it again once the receiver works. An endpoint receives the events recorded after it was created.

Its signing headers differ from the table above in these:

What it holds

An example:

{
  "type": "programme.updated",
  "timestamp": "2026-09-16T10:00:05.000Z",
  "data": {
    "store_key": "example-store",
    "version": "3f1c9a2b7d4e5f60718293a4b5c6d7e8",
    "changed": [
      "rewards"
    ],
    "changed_by": "api_key",
    "audit_id": "5b2f1c7e-8d4a-4e3b-9f6a-1c2d3e4f5a6b"
  }
}

Answer 2XX: Received. Anything else, a redirect, or no answer within 15 seconds is retried.

webhook.test — A test, sent only by POST /webhooks/{endpoint_id}/test

Signed like every event; sent once, never retried, never counted towards disabling.

Its signing headers differ from the table above in these:

What it holds

An example:

{
  "type": "webhook.test",
  "timestamp": "2026-09-16T10:00:00.000Z",
  "data": {
    "endpoint_id": "we_Q3mN8xR2vT6pL9wK4sJ7hF1d"
  }
}

Answer 2XX: Received. A test is sent once and is not retried: any other answer, a redirect, or no answer within 15 seconds is reported by POST /webhooks/{endpoint_id}/test as not delivered, and never counts towards disabling the endpoint.