Reference
@grizzlee/sdk/webhooks
verifyWebhook
Verify the untouched request body before parsing JSON or processing an event.
declare const verifyWebhook: (input: { secret: string; body: string; eventId: string; signature: string; now?: number | undefined; toleranceSeconds?: number | undefined; }) => boolean;parseWebhookEvent
Verify the raw body with verifyWebhook first. Throws for invalid JSON or payloads.
declare const parseWebhookEvent: (body: string) => GrizzleeWebhookEvent;ReferralSelection
type ReferralSelection = { winner: { programId: string; partnerId: string; occurredAt: string; type?: "code" | "receipt" | undefined; providerPromoCodeId?: string | undefined; index?: number | undefined; } | null; skipped: { index: number; reason: "expired" | "invalid" | "self_referral" | "wrong_program" | "program_inactive" | "partner_inactive" | "fraud" | "customer_already_referred" | "older"; }[]; };ReferralSkipReason
type ReferralSkipReason = "expired" | "invalid" | "self_referral" | "wrong_program" | "program_inactive" | "partner_inactive" | "fraud" | "customer_already_referred" | "older";GrizzleeWebhookEvent
Switch on type to narrow data to that event's payload.
type GrizzleeWebhookEvent = { id: string; companyId: string; type: "order.refunded"; data: OrderRefundedWebhookPayload; createdAt: string; } | { id: string; companyId: string; type: "order.adjusted"; data: OrderAdjustedWebhookPayload; createdAt: string; } | { id: string; companyId: string; type: "order.completed"; data: OrderCompletedWebhookPayload; createdAt: string; } | { id: string; companyId: string; type: "partner.created"; data: PartnerCreatedWebhookPayload; createdAt: string; } | { id: string; companyId: string; type: "reward.created"; data: RewardCreatedWebhookPayload; createdAt: string; } | { id: string; companyId: string; type: "reward.approved"; data: RewardApprovedWebhookPayload; createdAt: string; } | { id: string; companyId: string; type: "reward.reversed"; data: RewardReversedWebhookPayload; createdAt: string; } | { id: string; companyId: string; type: "reward.restored"; data: RewardRestoredWebhookPayload; createdAt: string; } | { id: string; companyId: string; type: "reward.adjusted"; data: RewardAdjustedWebhookPayload; createdAt: string; } | { id: string; companyId: string; type: "reward.delivered"; data: RewardDeliveredWebhookPayload; createdAt: string; } | { id: string; companyId: string; type: "reward.delivery_failed"; data: RewardDeliveryFailedWebhookPayload; createdAt: string; } | { id: string; companyId: string; type: "reward.debt_recorded"; data: RewardDebtRecordedWebhookPayload; createdAt: string; } | { id: string; companyId: string; type: "reward.debt_settled"; data: RewardDebtSettledWebhookPayload; createdAt: string; } | { id: string; companyId: string; type: "payout.created"; data: PayoutWebhookPayload; createdAt: string; } | { id: string; companyId: string; type: "payout.paid"; data: PayoutWebhookPayload; createdAt: string; } | { id: string; companyId: string; type: "payout.reversed"; data: PayoutReversedWebhookPayload; createdAt: string; } | { id: string; companyId: string; type: "payout.failed"; data: PayoutWebhookPayload; createdAt: string; } | { id: string; companyId: string; type: "payout.needs_action"; data: PayoutWebhookPayload; createdAt: string; } | { id: string; companyId: string; type: "payout.cancelled"; data: PayoutWebhookPayload; createdAt: string; } | { id: string; companyId: string; type: "payout.account_required"; data: PayoutAccountRequiredWebhookPayload; createdAt: string; } | { id: string; companyId: string; type: "credit.redeemed"; data: CreditRedeemedWebhookPayload; createdAt: string; } | { id: string; companyId: string; type: "credit.restored"; data: CreditRestoredWebhookPayload; createdAt: string; } | { id: string; companyId: string; type: "incentive.flagged"; data: IncentiveFlaggedWebhookPayload; createdAt: string; } | { id: string; companyId: string; type: "self_referral.detected"; data: SelfReferralDetectedWebhookPayload; createdAt: string; } | { id: string; companyId: string; type: "fraud.flagged"; data: FraudFlaggedWebhookPayload; createdAt: string; } | { id: string; companyId: string; type: "referral.displaced"; data: ReferralDisplacedWebhookPayload; createdAt: string; } | { id: string; companyId: string; type: "milestone.reported"; data: MilestoneReportedWebhookPayload; createdAt: string; } | { id: string; companyId: string; type: "milestone.revoked"; data: MilestoneRevokedWebhookPayload; createdAt: string; } | { id: string; companyId: string; type: "milestone.reinstated"; data: MilestoneReinstatedWebhookPayload; createdAt: string; } | { id: string; companyId: string; type: "milestone.reversed"; data: MilestoneReversedWebhookPayload; createdAt: string; } | { id: string; companyId: string; type: "partner.erased"; data: PartnerErasedWebhookPayload; createdAt: string; } | { id: string; companyId: string; type: "customer.erased"; data: CustomerErasedWebhookPayload; createdAt: string; };GrizzleeWebhookEventType
type GrizzleeWebhookEventType = "order.refunded" | "order.adjusted" | "order.completed" | "partner.created" | "reward.created" | "reward.approved" | "reward.reversed" | "reward.restored" | "reward.adjusted" | "reward.delivered" | "reward.delivery_failed" | "reward.debt_recorded" | "reward.debt_settled" | "payout.created" | "payout.paid" | "payout.reversed" | "payout.failed" | "payout.needs_action" | "payout.cancelled" | "payout.account_required" | "credit.redeemed" | "credit.restored" | "incentive.flagged" | "self_referral.detected" | "fraud.flagged" | "referral.displaced" | "milestone.reported" | "milestone.revoked" | "milestone.reinstated" | "milestone.reversed" | "partner.erased" | "customer.erased";GrizzleeWebhookPayloads
type GrizzleeWebhookPayloads = GrizzleeWebhookPayloads;WebhookPartnerReference
type WebhookPartnerReference = WebhookPartnerReference;RewardWebhookPayload
Switch on trigger, or check milestone, to read the order or the milestone.
type RewardWebhookPayload = RewardWebhookFields & RewardWebhookSource;RewardCreatedWebhookPayload
Keeps the original raw reward fields as well as the nested reward.
type RewardCreatedWebhookPayload = RewardWebhookPayload & Reward;RewardApprovedWebhookPayload
type RewardApprovedWebhookPayload = RewardWebhookPayload & Reward;RewardReversedWebhookPayload
Sent after a refund, a milestone revocation or a milestone report reversal reverses part or all of a reward.
type RewardReversedWebhookPayload = RewardWebhookPayload & { reversalCents: number; };RewardRestoredWebhookPayload
Sent after a lower refund total, a milestone reinstatement or a milestone report that brings the count back to the threshold gives back part or all of a reversed reward.
type RewardRestoredWebhookPayload = RewardWebhookPayload & { restoredCents: number; };RewardAdjustedWebhookPayload
Sent when an order adjustment changed what an order reward is worth. changeCents is signed: positive when the order total went up, negative when it went down.
type RewardAdjustedWebhookPayload = RewardWebhookPayload & { eventId: string; changeCents: number; };RewardDeliveredWebhookPayload
type RewardDeliveredWebhookPayload = RewardWebhookPayload & { delivery: RewardDelivery; };RewardDeliveryFailedWebhookPayload
type RewardDeliveryFailedWebhookPayload = RewardWebhookPayload & { delivery: RewardDelivery; };RewardDebtRecordedWebhookPayload
Sent when a reversal leaves the partner holding part of a reward the merchant already delivered. debt is the new debt with outstandingCents equal to amountCents.
type RewardDebtRecordedWebhookPayload = RewardWebhookPayload & { debt: PartnerDeliveryDebt; };RewardDebtSettledWebhookPayload
Sent once for each settlement of a delivery debt. reward is the reward the debt belongs to. debt shows its outstandingCents and settlements right after this settlement.
type RewardDebtSettledWebhookPayload = RewardWebhookPayload & { debt: PartnerDeliveryDebt; settlement: DeliveryDebtSettlement; settledCents: number; };PayoutWebhookPayload
type PayoutWebhookPayload = PayoutWebhookPayload;PayoutReversedWebhookPayload
type PayoutReversedWebhookPayload = PayoutReversedWebhookPayload;PayoutAccountRequiredWebhookPayload
Sent when a scheduled run creates no payout for a partner because the schedule waits for a Stripe account and the partner has none. Sent once per wait: later runs that skip the same partner send nothing until the partner is paid or has nothing payable at a run. The amounts are what the run would have paid. The rewards stay payable and roll over.
type PayoutAccountRequiredWebhookPayload = PayoutAccountRequiredWebhookPayload;PartnerCreatedWebhookPayload
type PartnerCreatedWebhookPayload = PartnerCreatedWebhookPayload;OrderWebhookPartners
type OrderWebhookPartners = OrderWebhookPartners;OrderCompletedWebhookPayload
type OrderCompletedWebhookPayload = { type: "order.completed"; customerId: string; orderId: string; occurredAt: string; eventId: string; commissionableCents: number; currency: "CAD" | "USD" | "EUR" | "GBP"; customerDisplayName?: string | undefined; newCustomer?: boolean | undefined; categories?: string[] | undefined; customerOrderNumber?: number | undefined; totalCents?: number | undefined; customerEmail?: string | undefined; incentiveAppliedCents?: number | undefined; } & OrderWebhookPartners & { customerOrderNumber?: number | undefined; reportedCustomerOrderNumber?: number | undefined; incentiveFlag?: IncentiveFlag | undefined; referralSelection?: { winner: { programId: string; partnerId: string; occurredAt: string; type?: "code" | "receipt" | undefined; providerPromoCodeId?: string | undefined; index?: number | undefined; } | null; skipped: { index: number; reason: "expired" | "invalid" | "self_referral" | "wrong_program" | "program_inactive" | "partner_inactive" | "fraud" | "customer_already_referred" | "older"; }[]; } | undefined; };OrderRefundedWebhookPayload
type OrderRefundedWebhookPayload = { type: "order.refunded"; orderId: string; occurredAt: string; eventId: string; refundedTotalCents?: number | undefined; refundedCommissionableCents?: number | undefined; fullRefund?: boolean | undefined; } & OrderWebhookPartners;OrderAdjustedWebhookPayload
Sent once for each applied order adjustment. A stale adjustment sends nothing. Each reward whose value changed also sends reward.adjusted.
type OrderAdjustedWebhookPayload = { type: "order.adjusted"; orderId: string; occurredAt: string; eventId: string; reason?: string | undefined; totalCents?: number | undefined; commissionableCents?: number | undefined; } & OrderWebhookPartners & { customerId: string; currency: "CAD" | "USD" | "EUR" | "GBP"; previousTotalCents?: number | undefined; previousCommissionableCents?: number | undefined; rewardIds: string[]; rewardChangeCents: number; };CreditRedeemedWebhookPayload
type CreditRedeemedWebhookPayload = CreditRedeemedWebhookPayload;CreditRestoredWebhookPayload
type CreditRestoredWebhookPayload = CreditRestoredWebhookPayload;IncentiveFlaggedWebhookPayload
Sent with order.completed when Grizzlee accepted an order whose incentiveAppliedCents did not match its reservation.
type IncentiveFlaggedWebhookPayload = IncentiveFlaggedWebhookPayload;SelfReferralDetectedWebhookPayload
Sent when a new completed order or milestone report matched a linked customer ID or the referring partner's identity signals. blocked: the program created no reward. review: rewardId names the reward held as pending. flagged: rewardId names a reward that follows the usual approval. signals lists the matching signal types, never their values.
type SelfReferralDetectedWebhookPayload = WebhookPartnerReference & SelfReferralMatch & ({ eventId: string; programId: string; customerId: string; rewardId?: string | undefined; } & ({ trigger: "order"; orderId: string; } | { trigger: "milestone"; milestone: string; }));FraudFlaggedWebhookPayload
Sent when fraud rules fired on a new completed order or milestone report. It covers every rule in fraudRuleIds. Self-referral matches keep their own self_referral.detected event, and a referral that triggers both sends both. blocked: the program created no reward. review: rewardId names the reward held as pending. flagged: rewardId names a reward that follows the usual approval. rules lists rule IDs and signal types, never values.
type FraudFlaggedWebhookPayload = WebhookPartnerReference & FraudMatch & ({ eventId: string; programId: string; customerId: string; rewardId?: string | undefined; } & ({ trigger: "order"; orderId: string; } | { trigger: "milestone"; milestone: string; }));ReferralDisplacedWebhookPayload
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.
type ReferralDisplacedWebhookPayload = ReferralDisplacedWebhookPayload;MilestoneWebhookFields
Fields of milestone.reported, milestone.revoked, milestone.reinstated and milestone.reversed. partners lists the distinct partners from the decisions and rewards, with top-level partnerId and partnerExternalId when there is one.
type MilestoneWebhookFields = MilestoneWebhookFields;MilestoneReportedWebhookPayload
Sent once for each new milestone report, rewarded or not.
type MilestoneReportedWebhookPayload = MilestoneReportedWebhookPayload;MilestoneRevokedWebhookPayload
Sent when a milestone is revoked for a person. Revoking it again while it is revoked sends nothing. After a reinstatement, the next revocation sends it again.
type MilestoneRevokedWebhookPayload = MilestoneRevokedWebhookPayload;MilestoneReinstatedWebhookPayload
Sent when a revoked milestone is reinstated for a person. A reinstatement of a milestone that is not revoked sends nothing.
type MilestoneReinstatedWebhookPayload = MilestoneReinstatedWebhookPayload;MilestoneReversedWebhookPayload
Sent when a report is reversed. Reversing a report that is already reversed sends nothing. rewardIds lists every reward for the person and milestone. The report's own rewards and bonuses whose count fell below their saved threshold reverse and also send reward.reversed.
type MilestoneReversedWebhookPayload = MilestoneReversedWebhookPayload;PartnerErasedWebhookPayload
Sent the first time a merchant erases a partner. The partner keeps its IDs and amounts.
type PartnerErasedWebhookPayload = PartnerErasedWebhookPayload;CustomerErasedWebhookPayload
Sent the first time a merchant erases a customer. Orders and rewards keep the customer ID.
type CustomerErasedWebhookPayload = CustomerErasedWebhookPayload;