> This page is for version 2024-10-01 (default).
> For other versions, use one of these documentation indexes:
> - 2024-10-01 (default): https://docs.getkard.com/2024-10-01/llms.txt
> - Legacy: https://docs.getkard.com/legacy/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.getkard.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.getkard.com/_mcp/server.

# Notification Webhook

POST 

This is an outbound webhook for issuers to receive notifications from Kard.
Learn more about how to configure, ingest and trigger your notification
webhooks [here](/2024-10-01/api/notifications).

Reference: https://docs.getkard.com/api/notifications/notification-webhook

## Request

### Payload

- `data` (NotificationDataUnion, required)
- `meta` (NotificationMetadata, optional)
- `errors` (list of ErrorObject, optional)

## Types

### NotificationDataUnion

- `type`: `earnedRewardApproved`
  - `attributes` (EarnedRewardNotificationAttributes, required)
  - `id` (string, required) — The internal ID of the notification
  - `relationships` (EarnedRewardRelationships, required)
- `type`: `earnedRewardSettled`
  - `attributes` (EarnedRewardSettledAttributes, required)
  - `id` (string, required) — The internal ID of the notification
  - `relationships` (EarnedRewardRelationships, required)
- `type`: `earnedRewardRejected`
  - `attributes` (EarnedRewardRejectedAttributes, required)
  - `id` (string, required) — The internal ID of the notification
  - `relationships` (RejectedTransactionRelationships, required)
- `type`: `auditUpdate`
  - `attributes` (AuditUpdateAttributes, required)
  - `id` (string, required) — The internal ID of the notification
  - `relationships` (AuditUpdateRelationships, required)
- `type`: `fileProcessingResult`
  - `attributes` (FileMetadataAttribute, required)
  - `id` (string, required) — The internal ID of the notification
- `type`: `pushNotificationPlacementFile`
  - `attributes` (PushNotificationPlacementFileAttributes, required)
  - `id` (string, required) — The placement ID, also used as the notification resource ID
  - `relationships` (PushNotificationPlacementFileRelationships, required)
- `type`: `emailNotificationPlacementFile`
  - `attributes` (EmailNotificationPlacementFileAttributes, required)
  - `id` (string, required) — The placement ID, also used as the notification resource ID
  - `relationships` (EmailNotificationPlacementFileRelationships, required)

### NotificationMetadata

- `issuerId` (string, required)
- `issuerName` (string, required)

### ErrorObject

- `status` (string, required) — Status code returned from the request
- `title` (string, required) — Name of error
- `detail` (string, required) — Description of the specific occurance of the error
- `source` (ErrorSource, optional) — An object containing a reference to the primary source of the error
- `id` (string, optional) — The id of the resource which caused the error. Always returned for multi-status errors.

### EarnedRewardNotificationAttributes

- `message` (string, required) — The display message associated to the notification
- `name` (string, required) — The name of the merchant
- `attributionUrl` (string, required) — The attribution URL to track user's interactions with the notification
- `transactionId` (string, required) — The transaction ID
- `transactionAmountInCents` (integer, required) — The amount of the originating transaction in cents
- `userReward` (UserReward, required) — Type of commission on offer (% or a flat $)
- `surveyUrl` (string, optional) — Post experience survey URL, if available. This will be present for rewards associated with local offers.
- `cardProductId` (string, optional) — The ID of the card product
- `transactionTimestamp` (datetime, optional) — The timestamp of the originating transaction in ISO format
- `categoryName` (string, optional) — The category of the offer, e.g. "Food & Dining"
- `assets` (list of MerchantAsset, optional) — Tracked asset images for the merchant. The asset URL is signed for attribution tracking and should be loaded as-is by the client.
- `purchaseChannel` (list of enum, optional) — The purchase channels the offer applies to
  - Allowed values: `INSTORE`, `ONLINE`

### EarnedRewardRelationships

- `user` (RelationshipSingle, required)
- `offer` (RelationshipSingle, required)
- `transaction` (RelationshipSingle, required)

### EarnedRewardSettledAttributes

- `attributionUrl` (string, required) — The attribution URL to track user's interactions with the notification
- `commissionEarned` (CommissionValue, required)
- `message` (string, required) — The display message associated to the notification
- `name` (string, required) — The name of the merchant
- `transactionAmountInCents` (integer, required) — The amount of the originating transaction in cents
- `transactionId` (string, required) — The transaction ID
- `userReward` (UserReward, required) — Type of commission on offer (% or a flat $)
- `assets` (list of MerchantAsset, optional) — Tracked asset images for the merchant. The asset URL is signed for attribution tracking and should be loaded as-is by the client.
- `cardProductId` (string, optional) — The ID of the card product
- `categoryName` (string, optional) — The category of the offer, e.g. "Food & Dining"
- `purchaseChannel` (list of enum, optional) — The purchase channels the offer applies to
  - Allowed values: `INSTORE`, `ONLINE`
- `surveyUrl` (string, optional) — Post experience survey URL, if available. This will be present for rewards associated with local offers.
- `transactionTimestamp` (datetime, optional) — The timestamp of the originating transaction in ISO format

### EarnedRewardRejectedAttributes

- `reason` (enum, required) — The reason code for why the transaction did not result in a reward
  - Allowed values: `AGGREGATOR_CARD_OVERLAP`, `MAX_REDEMPTION_LIMIT_REACHED`, `SETTLEMENT_REJECTED`, `USER_NOT_ENROLLED`, `USER_NOT_IN_AUDIENCE_SEGMENT`
- `message` (string, required) — The display message associated to the notification
- `transactionId` (string, required) — The transaction ID
- `transactionAmountInCents` (integer, required) — The amount of the originating transaction in cents
- `transactionTimestamp` (datetime, optional) — The timestamp of the originating transaction in ISO format

### RejectedTransactionRelationships

- `user` (RelationshipSingle, required)
- `transaction` (RelationshipSingle, required)

### AuditUpdateAttributes

- `status` (enum, required) — The status of the audit
  - Allowed values: `NEW`, `IN_PROGRESS`, `CLOSED`
- `auditCode` (integer, required) — Audit Code - Enum. Code to define audit.`3005` : Customer is claiming cashback is incorrect - INCORRECT CASHBACK CLAIM`3006` : Transaction is missing the cashback award - MISSING CASHBACK AWARD`8001` : Other - check audit description
- `merchantName` (string, required) — The merchant name related to the transaction audit
- `auditDescription` (string, required) — The description of the audit
- `transactionId` (string, required) — The transaction ID associated with audit
- `resolutionCode` (integer, optional) — Resolution Code - Enum. field is available when audit is status CLOSED.`5001` : Transaction will be deleted`5002` : Settlement amount will be adjusted`5003` : Return amount will be adjusted`5004` : Reward dispute resolved`5005` : Transaction will be marked for writeoff`5006` : Transaction will be marked as rejected`5007` : Transaction will be resent through webhook`5008` : Transaction will be resent through daily file`5009` : No change needed`9001` : Ineligible item in purchase`9002` : Return was made`9003` : User ineligible for offer (usually because of participation through another program)`9004` : Redemption limit hit (if offer has a set number of redemptions and it isn't handled programmatically)`9005` : Transaction not captured
- `resolutionDescription` (string, optional) — The resolution description; field is available when audit is status CLOSED
- `resolutionTimeStamp` (datetime, optional) — The resolution timestamp of when the audit was marked as status CLOSED in ISO format; available when audit is closed.

### AuditUpdateRelationships

- `user` (RelationshipSingle, required)
- `audit` (RelationshipSingle, required)

### FileMetadataAttribute

- `fileName` (string, required) — The name of the file.
- `sentAt` (string, required) — ISO 8601 timestamp (ISO8601) when the file was originally sent/created.
- `lastModified` (string, required) — ISO 8601 timestamp (ISO8601) when the file was last modified.
- `downloadUrl` (string, required) — Temporary URL that provides direct access to download the file for 30 minutes.

### PushNotificationPlacementFileAttributes

- `placementName` (string, required) — The display name of the placement
- `availableSlots` (integer, required) — The number of offer slots available in the placement
- `cadence` (string, required) — The delivery cadence of the placement (e.g. WEEKLY)
- `downloadUrl` (string, required) — Presigned URL to download the generated placement file (gzipped JSONL)

### PushNotificationPlacementFileRelationships

- `placement` (RelationshipSingle, required)
- `contentStrategy` (RelationshipSingle, optional)

### EmailNotificationPlacementFileAttributes

- `name` (string, required) — The display name of the placement
- `organizationId` (string, required) — The issuer organization ID the placement belongs to
- `availableSlots` (integer, required) — The number of offer slots available in the placement
- `cadence` (string, required) — The delivery cadence of the placement (e.g. MONTHLY)
- `downloadUrl` (string, required) — Presigned URL to download the generated placement file (gzipped JSONL)

### EmailNotificationPlacementFileRelationships

- `placement` (RelationshipSingle, required)
- `contentStrategy` (RelationshipSingle, optional)

### ErrorSource

- `pointer` (string, optional) — A JSON pointer to the value in the request document that caused the error
- `parameter` (string, optional) — A string indicating which URI query parameter caused the error
- `header` (string, optional) — A string indicating the name of a single request header which caused the error

### UserReward

- `type` (enum, required) — The type of reward (% or a flat $)
  - Allowed values: `FLAT`, `PERCENT`
- `value` (double, required) — The reward value

### MerchantAsset

- `type` (enum, required) — The type of asset being tracked.
  - Allowed values: `IMG_VIEW`, `BANNER_VIEW`
- `url` (string, required) — Attribution-signed URL for loading the asset.
- `alt` (string, optional) — Alt text describing the asset for accessibility.

### RelationshipSingle

- `data` (RelationshipData, required)

### CommissionValue

- `type` (enum, required) — The type of commission
  - Allowed values: `cents`
- `value` (integer, required) — The commission value.

### RelationshipData

- `type` (string, required) — Type of document returned
- `id` (string, required) — The ID of the related resource