Webhook events

payout.needs_action

Receive this event when Grizzlee records payout.needs_action.

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": "payout.needs_action",
  "data": {
    "partnerId": "partner-example",
    "partnerExternalId": "merchant-partner-001",
    "id": "payout-example",
    "companyId": "company-example",
    "currency": "CAD",
    "amountCents": 500,
    "status": "needs_action",
    "provider": "manual",
    "eventId": "payment-example",
    "createdAt": "2026-10-11T12:00:00.000Z",
    "updatedAt": "2026-10-11T12:00:00.000Z",
    "allocations": [
      {
        "id": "allocation-example",
        "companyId": "company-example",
        "payoutId": "payout-example",
        "partnerId": "partner-example",
        "rewardId": "reward-example",
        "orderId": "order-example",
        "programId": "program-example",
        "currency": "CAD",
        "amountCents": 500,
        "createdAt": "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
`id`	string	Yes
`companyId`	string	Yes
`currency`	"CAD", "USD", "EUR", "GBP"	Yes
`amountCents`	integer	Yes	minimum 0. maximum 1000000000000
`nettedDebtCents`	integer	No	minimum 0. maximum 1000000000000
`netAmountCents`	integer	No	minimum 0. maximum 1000000000000
`status`	"queued", "processing", "needs_action", "paid", "failed", "cancelled", "reversed"	Yes
`provider`	"manual", "stripe"	Yes
`mode`	"merchant", "grizzlee_wallet"	No
`integrationId`	string	No
`destination`	string	No
`providerReference`	string	No
`transferGroup`	string	No
`paidAt`	string	No	date-time
`reversedCents`	integer	No	minimum 0. maximum 1000000000000
`reversedAt`	string	No	date-time
`lastError`	string	No
`lastErrorParts`	array	No
`eventId`	string	Yes
`schedule`	object	No
`createdAt`	string	Yes	date-time
`updatedAt`	string	Yes	date-time
`allocations`	array	Yes

lastErrorParts[]

Field	Type	Required	Details
`lastErrorParts.code`	string	Yes
`lastErrorParts.params`	object	No

schedule

Field	Type	Required	Details
`schedule.dueOn`	string	Yes
`schedule.approvedBefore`	string	Yes	date-time

allocations[]

Field	Type	Required	Details
`allocations.id`	string	Yes
`allocations.companyId`	string	Yes
`allocations.payoutId`	string	Yes
`allocations.partnerId`	string	Yes
`allocations.rewardId`	string	Yes
`allocations.orderId`	string	No
`allocations.milestone`	string	No
`allocations.programId`	string	Yes
`allocations.currency`	"CAD", "USD", "EUR", "GBP"	Yes
`allocations.amountCents`	integer	Yes	minimum 0. maximum 1000000000000
`allocations.createdAt`	string	Yes	date-time

Payload schema

json

{
  "type": "object",
  "properties": {
    "partnerId": {
      "type": "string",
      "minLength": 1
    },
    "partnerExternalId": {
      "type": "string",
      "minLength": 1
    },
    "id": {
      "type": "string",
      "minLength": 1
    },
    "companyId": {
      "type": "string",
      "minLength": 1
    },
    "currency": {
      "type": "string",
      "enum": [
        "CAD",
        "USD",
        "EUR",
        "GBP"
      ]
    },
    "amountCents": {
      "type": "integer",
      "minimum": 0,
      "maximum": 1000000000000
    },
    "nettedDebtCents": {
      "type": "integer",
      "minimum": 0,
      "maximum": 1000000000000
    },
    "netAmountCents": {
      "type": "integer",
      "minimum": 0,
      "maximum": 1000000000000
    },
    "status": {
      "type": "string",
      "enum": [
        "queued",
        "processing",
        "needs_action",
        "paid",
        "failed",
        "cancelled",
        "reversed"
      ]
    },
    "provider": {
      "type": "string",
      "enum": [
        "manual",
        "stripe"
      ]
    },
    "mode": {
      "type": "string",
      "enum": [
        "merchant",
        "grizzlee_wallet"
      ]
    },
    "integrationId": {
      "type": "string",
      "minLength": 1
    },
    "destination": {
      "type": "string",
      "minLength": 1
    },
    "providerReference": {
      "type": "string",
      "minLength": 1
    },
    "transferGroup": {
      "type": "string",
      "minLength": 1
    },
    "paidAt": {
      "type": "string",
      "format": "date-time"
    },
    "reversedCents": {
      "type": "integer",
      "minimum": 0,
      "maximum": 1000000000000
    },
    "reversedAt": {
      "type": "string",
      "format": "date-time"
    },
    "lastError": {
      "type": "string"
    },
    "lastErrorParts": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string",
            "minLength": 1
          },
          "params": {
            "type": "object",
            "additionalProperties": {}
          }
        },
        "required": [
          "code"
        ],
        "additionalProperties": true
      }
    },
    "eventId": {
      "type": "string",
      "minLength": 1
    },
    "schedule": {
      "type": "object",
      "properties": {
        "dueOn": {
          "type": "string",
          "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
        },
        "approvedBefore": {
          "type": "string",
          "format": "date-time"
        }
      },
      "required": [
        "dueOn",
        "approvedBefore"
      ],
      "additionalProperties": true
    },
    "createdAt": {
      "type": "string",
      "format": "date-time"
    },
    "updatedAt": {
      "type": "string",
      "format": "date-time"
    },
    "allocations": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "minLength": 1
          },
          "companyId": {
            "type": "string",
            "minLength": 1
          },
          "payoutId": {
            "type": "string",
            "minLength": 1
          },
          "partnerId": {
            "type": "string",
            "minLength": 1
          },
          "rewardId": {
            "type": "string",
            "minLength": 1
          },
          "orderId": {
            "type": "string",
            "minLength": 1
          },
          "milestone": {
            "type": "string",
            "minLength": 1
          },
          "programId": {
            "type": "string",
            "minLength": 1
          },
          "currency": {
            "type": "string",
            "enum": [
              "CAD",
              "USD",
              "EUR",
              "GBP"
            ]
          },
          "amountCents": {
            "type": "integer",
            "minimum": 0,
            "maximum": 1000000000000
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          }
        },
        "required": [
          "id",
          "companyId",
          "payoutId",
          "partnerId",
          "rewardId",
          "programId",
          "currency",
          "amountCents",
          "createdAt"
        ],
        "additionalProperties": true
      }
    }
  },
  "required": [
    "partnerId",
    "partnerExternalId",
    "id",
    "companyId",
    "currency",
    "amountCents",
    "status",
    "provider",
    "eventId",
    "createdAt",
    "updatedAt",
    "allocations"
  ],
  "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.