Webhook events

referral.displaced

Sent when a referral by another partner took over a customer's attribution in a program before a purchase or milestone locked it. partnerId names the new partner.

Example payload

This illustrative payload follows the current event validator. Amounts use minor units.

json

{
  "id": "00000000-0000-4000-8000-000000000001",
  "companyId": "company-example",
  "type": "referral.displaced",
  "data": {
    "partnerId": "partner-example",
    "partnerExternalId": "merchant-partner-001",
    "attributionId": "attributionId-example",
    "programId": "program-example",
    "customerId": "customer-example",
    "orderId": "order-example",
    "channel": "link",
    "occurredAt": "2026-10-11T12:00:00.000Z",
    "previousPartnerId": "previous-partner-example",
    "previousPartnerExternalId": "merchant-partner-002",
    "previousOccurredAt": "2026-10-11T12:00:00.000Z"
  },
  "createdAt": "2026-10-11T12:00:00.000Z"
}

Payload fields

Field	Type	Required	Details
`partnerId`	string	Yes
`partnerExternalId`	string	Yes
`attributionId`	string	Yes
`programId`	string	Yes
`customerId`	string	Yes
`orderId`	string	No
`channel`	"link", "qr", "coupon", "in_app"	Yes
`occurredAt`	string	Yes	date-time
`previousPartnerId`	string	Yes
`previousPartnerExternalId`	string	Yes
`previousOccurredAt`	string	Yes	date-time

Payload schema

json

{
  "type": "object",
  "properties": {
    "partnerId": {
      "type": "string",
      "minLength": 1
    },
    "partnerExternalId": {
      "type": "string",
      "minLength": 1
    },
    "attributionId": {
      "type": "string",
      "minLength": 1
    },
    "programId": {
      "type": "string",
      "minLength": 1
    },
    "customerId": {
      "type": "string",
      "minLength": 1
    },
    "orderId": {
      "type": "string",
      "minLength": 1
    },
    "channel": {
      "type": "string",
      "enum": [
        "link",
        "qr",
        "coupon",
        "in_app"
      ]
    },
    "occurredAt": {
      "type": "string",
      "format": "date-time"
    },
    "previousPartnerId": {
      "type": "string",
      "minLength": 1
    },
    "previousPartnerExternalId": {
      "type": "string",
      "minLength": 1
    },
    "previousOccurredAt": {
      "type": "string",
      "format": "date-time"
    }
  },
  "required": [
    "partnerId",
    "partnerExternalId",
    "attributionId",
    "programId",
    "customerId",
    "channel",
    "occurredAt",
    "previousPartnerId",
    "previousPartnerExternalId",
    "previousOccurredAt"
  ],
  "additionalProperties": true
}

Handle delivery

Verify the signature over the raw body before parsing JSON. Check that the body ID matches Grizzlee-Event-Id. Process each ID once, since delivery can repeat.