> For the complete documentation index, see [llms.txt](https://help.impact.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.impact.com/brand/zh/what-would-you-like-to-learn-about/account-administration/account-settings/notifications/enable-event-notification-postbacks-for-brands.md).

# 为品牌启用事件通知回传

事件通知回调（Webhook）会在特定事件发生时实时通知您的内部系统。虽然发送的数据因事件而异，但所有事件的配置流程都相同。

{% stepper %}
{% step %}

## 访问事件通知回调

1. 在顶部导航栏中，选择 ![](https://1186853034-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FwMLlMoFBtKJa8ptd3zaw%2Fuploads%2F210dEQa93qyQgoJDkieL%2FUser%20profile.svg?alt=media\&token=f84c5b17-fae4-4a30-990a-9de5e57a150b) **\[用户个人资料] → 设置**.
2. 在 *技术* 部分中，选择 [**事件通知**](https://app.impact.com/secure/advertiser/accountSettings/techintegration/view-edit-adv-pingback-settings-flow.ihtml?).
   {% endstep %}

{% step %}

## 填写全局配置字段

1. 将鼠标悬停在您要配置通知回调的事件上，然后选择 ![](https://1186853034-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FwMLlMoFBtKJa8ptd3zaw%2Fuploads%2Fkka3dqJOx8ZhiX82RDLt%2FEdit_light.svg?alt=media\&token=f454405c-ebd8-49af-90db-22efc27476bf) **\[编辑]**.
2. 使用下表配置传送设置：

<table><thead><tr><th width="225.36328125">字段</th><th>说明</th></tr></thead><tbody><tr><td>网址</td><td>用于接收数据的服务器端点。</td></tr><tr><td>HTTP 方法</td><td><p><code>GET</code>：数据会作为查询字符串附加到 URL。</p><p><code>POST</code>：数据会在请求正文中发送，其中包含多个可设置的可选参数。<br><br>有关各事件及其负载内容的更多信息，请参阅 <a href="#notification-events-and-payloads">通知事件和负载</a> 。</p></td></tr><tr><td>HTTP 标头</td><td>（可选）添加用于身份验证的自定义标头（例如， <code>Authorization: Bearer token</code>).</td></tr><tr><td>最小延迟</td><td>设置 <em>最小延迟</em> （秒），以保护您的服务器免受流量激增的影响。</td></tr><tr><td>最大请求数</td><td>设置 <em>最大请求数</em> （每秒），以保护您的服务器免受流量激增的影响。</td></tr><tr><td>成功响应</td><td>服务器成功处理回调时返回的特定文本字符串或 HTTP 状态码。</td></tr><tr><td>错误响应</td><td>表示失败的文本字符串或状态码（例如， <code>ERROR</code> 或 <code>500</code>).</td></tr></tbody></table>
{% endstep %}
{% endstepper %}

## 通知事件和负载

每个事件通知都会发送一组独特的可配置数据项（例如， `{ActionId}`）。请参阅以下事件，了解可以从负载中提取哪些数据项。

<details>

<summary>操作生命周期事件</summary>

跟踪、修改或撤销操作时，操作生命周期事件会向指定 URL（以及任何包含的参数）发送 HTTP 请求。

```json
// JSON 格式的 POST 示例
{
  "CampaignId": 9876, // 计划 ID
  "ActionTrackerId": 12345, // 事件类型 ID
  "MediaPartnerId": 555, // 合作伙伴 ID
  "CampaignName": "Spring Global Promotion", // 计划名称
  "ActionTrackerName": "Standard Sale Tracker", // 事件类型名称
  "MediaPartnerName": "Top Tier Affiliates", // 合作伙伴名称
  "ActionId": "ACT-778899", // 操作 ID
  "Status": "MODIFIED", // 操作状态
  "StatusDetail": "Item return - payout adjusted", // 操作状态的更多详细信息
  "AdId": 44332, // 广告 ID
  "Payout": 10.50, // 支付给合作伙伴的操作佣金，使用合作伙伴的货币
  "DeltaPayout": -5.00, // 相对于先前操作的更正后佣金金额
  "IntendedPayout": 15.50, // 超限操作的预期佣金金额
  "Amount": 100.00, // 操作金额，使用账户货币
  "DeltaAmount": -50.00, // 相对于先前操作的更正后金额
  "IntendedAmount": 150.00, // 超限操作的预期销售金额
  "Currency": "USD", // 操作所用的货币
  "OriginalCurrency": "USD", // 操作的原始货币（即购物车货币）
  "OriginalAmount": 100.00, // 操作的原始金额（即购物车金额）
  // "items" 集合：此操作中各个商品的数据
  "items": [{join(items, i, 
  "\{\"sku\":\"{i.sku}\",
  \"item_price\":{i.amt},
  \"category\":\"{i.cat}\",
  \"quantity\":{i.qty},
  \"cartamt\":{i.cartamt},
  \"rbt\":\"{i.rbt}\",
  \"name\":\"{i.name}\"\}")}],
  "EventDate": "2026-04-08T09:00:00Z", // 转化日期
  "CreationDate": "2026-04-08T09:05:00Z", // 在系统中创建的日期
  "LockingDate": "2026-05-08T00:00:00Z", // 操作将被锁定的日期
  "ClearedDate": "2026-05-15T00:00:00Z", // 计划结算日期
  "ReferringDomain": "blog.partner.com", // 引荐域名
  "LandingPageUrl": "https://brand.com/sale", // 着陆页 URL
  "RefCustomerArea": "California", // 客户区域（根据 IP 推断）
  "RefCustomerCity": "San Francisco", // 客户城市（根据 IP 推断）
  "RefCustomerRegion": "CA", // 客户地区（根据 IP 推断）
  "RefCustomerCountry": "US", // 客户国家/地区代码（根据 IP 推断）
  "RefClickId": "CLK9988776655", // 唯一点击标识符
  "SharedId": "social_post_01", // 合作伙伴共享 ID
  "PromoCode": "SAVE20", // 通用促销代码
  "CustomerStatus": "EXISTING", // 客户状态
  "Oid": "ORD-554433", // 订单 ID
  "Note": "Partial return processed", // 随操作提供的备注
  "CustomerPostCode": "94105", // 客户邮政编码
  "CustomerCity": "San Francisco", // 客户城市
  "CustomerCountry": "US", // 客户国家/地区代码
  "CustomerRegion": "CA", // 客户地区
  "CustomerId": "CUST-12345", // 客户 ID
  "CustomerEmail": "a665a45920422f9d417...", // 已哈希处理的客户电子邮件
  "IpAddress": "192.168.1.1", // IP 地址
  "CallerId": null, // 来电者的电话号码
  // 自定义补充字段
  "Text1": "Custom Val 1", // 文本 1
  "Date1": "2026-04-08", // 日期 1
  "Money1": 10.00, // 金额 1
  "Numeric1": 1, // 数值 1
  // 设备和应用元数据
  "appPackage": "com.brand.app", // 移动应用包名
  "appName": "BrandStore", // 移动应用名称
  "appVersion": "4.2.1", // 移动应用版本
  "deviceOs": "iOS", // 设备操作系统
  "deviceOsVersion": "17.4", // 设备操作系统版本
  "deviceManuf": "Apple", // 设备制造商
  "deviceModel": "iPhone 15", // 设备型号
  "macAddress": "00:1B:44:11:3A:B7", // MAC 地址（大写）
  "macAddressLower": "00:1b:44:11:3a:b7", // MAC 地址（小写）
  "macAddressAlpha": "001B44113AB7", // MAC 地址（无冒号）
  "macAddressSha1": "47a32...", // MAC SHA1
  "iosIfa": "EA7583CD-A667-48BC-B806-42ECB2B48606", // iOS 广告标识符
  "iosAdTracking": "1", // iOS 广告跟踪设置
  "androidId": null, // Android ID
  "deviceId": "D-556677", // 设备 ID
  "deviceIp": "192.168.1.1" // 设备 IP
}
```

</details>

<details>

<summary>操作查询事件</summary>

创建或解决操作查询时，操作查询事件会向指定 URL（以及任何包含的参数）发送 HTTP 请求。

```json
// JSON 格式的 POST 示例
{
  "Id": 554433, // 系统中操作查询的唯一标识符
  "MediaPartnerId": 555, // 合作伙伴 ID
  "MediaPartnerName": "Top Tier Affiliates", // 合作伙伴名称
  "CampaignId": 9876, // 计划 ID
  "CampaignName": "Spring Global Promotion", // 计划名称
  "OrderId": "ORD-12345", // 所报告操作的订单 ID
  "TransactionDate": "2026-04-01T14:30:00Z", // 触发操作查询的事件的交易日期
  "TransactionAmount": 250.00, // 触发操作查询的事件的交易金额
  "InquiryType": "MISSING_ACTION", // 操作查询类型
  "ExpectedPayout": 25.00, // 合作伙伴预期的返佣金额
  "ResolutionDeadlineDate": "2026-05-01T00:00:00Z", // 必须接受或拒绝该查询的截止日期
  "TrackingLink": "https://proweb.com/click?cid=1&pid=555", // 合作伙伴提供的跟踪链接
  "ActionId": "ACT-999000", // 操作 ID（如与现有操作关联）
  "AutoApprovalDate": "2026-05-05T00:00:00Z", // 系统运行自动审批规则的日期
  "ResolutionStatus": "PENDING", // 操作查询的最终处理状态
  "RejectReason": null, // 操作查询被拒绝的原因
  "FinalPayout": 0.00, // 与操作查询关联的最终返佣金额
  "ResolutionDate": null, // 查询作出决定的日期
  "CreationDate": "2026-04-08T10:05:00Z", // 查询在系统中创建的日期
  "InquiryNotes": "Customer claims they clicked the link but no credit was shown.", // 合作伙伴提交的查询备注
  "ResolutionNotes": null, // 作出查询决定时提交的备注
  "Comments": "[{\"user\": \"support_agent\", \"text\": \"Verifying click logs now.\"}, {\"user\": \"partner\", \"text\": \"Customer provided receipt.\"}]" // 添加到查询中的评论（JSON 格式）
}
```

</details>

<details>

<summary>操作结算事件</summary>

操作结算时，操作结算事件会向指定 URL（以及任何包含的参数）发送 HTTP 请求。

```json
// JSON 格式的 POST 示例
{
  "ActionTrackerId": 12345, // 事件类型 ID
  "ActionTrackerName": "Standard Sale Tracker", // 事件类型名称
  "CampaignId": 9876, // 计划 ID
  "CampaignName": "Spring Global Promotion", // 计划名称
  "MediaPartnerId": 555, // 合作伙伴 ID
  "MediaPartnerName": "Top Tier Affiliates", // 合作伙伴名称
  "OrderIds": "ORD-9921,ORD-9922", // 所报告操作的订单 ID（以逗号分隔）
  "ActionIds": "ACT-101,ACT-102", // 操作 ID（以逗号分隔）
  "ClearedDate": "2026-04-15T12:00:00Z", // 操作计划结算的日期（ISO 8601）
  "LedgerDate": "2026-04-08T09:54:43Z" // 操作结算的日期（ISO 8601）
}
```

</details>

<details>

<summary>跟踪值请求事件</summary>

创建跟踪请求时，跟踪值请求事件会向指定 URL（以及任何包含的参数）发送 HTTP 请求。

```json
// JSON 格式的 POST 示例
{
  "CampaignId": 9876, // 计划 ID
  "ActionTrackerId": 12345, // 事件类型 ID
  "MediaPartnerId": 555, // 合作伙伴 ID
  "ActionId": "ACT-778899", // 操作 ID
  "Amount": 150.00, // 以账户货币计价的操作金额
  "Currency": "USD", // 操作所用的货币
  "Oid": "ORD-554433", // 订单 ID
  // "items" 集合：操作中各个商品的明细
  "items": [{join(items, i, "\{\"sku\":\"{i.sku}\",\"item_price\":{i.amt},\"category\":\"{i.cat}\",\"quantity\":{i.qty},\"cartamt\":{i.cartamt},\"rbt\":\"{i.rbt}\",\"name\":\"{i.name}\"\}")}],
  "EventDate": "2026-04-08T09:00:00Z", // 转化日期
  "IpAddress": "192.168.1.1", // 设备的 IP 地址
  "RefClickId": "CLK9988776655" // 唯一点击标识符
}
```

</details>

<details>

<summary>已完成的作业事件</summary>

当某项作业完成时，已完成的作业事件会向指定 URL（以及任何其他参数）发送 HTTP 请求，适用于 [报告导出](https://integrations.impact.com/brand-api-reference/reference/report-export/report-export) 或 [点击“导出”](https://integrations.impact.com/brand-api-reference/reference/clicks/clickexport).

```json
// JSON 格式的 POST 示例
{
  "JobId": 10293847, // 作业的唯一 ID
  "JobType": "REPORT_EXPORT", // 作业类型
  "AccountId": 7744, // 账户 ID
  "StartDate": "2026-04-08T10:00:05Z", // 作业开始时间
  "EndDate": "2026-04-08T10:11:02Z", // 作业完成时间
  "RecordsProcessed": 5240, // 已处理或生成的记录数
  "ApiJobDetailUri": "https://api.impact.com/jobs/10293847", // 用于获取作业详细信息的 API URI
  "ApiResultUri": "https://api.impact.com/jobs/10293847/result", // 用于获取作业输出结果的 API URI
  "ResultDownloadUrlExp5": "https://download.impact.com/file?token=a1b2...&exp=5min", // 用于下载输出内容的 URL（5 分钟后过期）
  "ResultDownloadUrlExp15": "https://download.impact.com/file?token=a1b2...&exp=15min", // 用于下载输出内容的 URL（15 分钟后过期）
  "ResultDownloadUrlExp30": "https://download.impact.com/file?token=a1b2...&exp=30min", // 用于下载输出内容的 URL（30 分钟后过期）
  "ResultDownloadUrlExp60": "https://download.impact.com/file?token=a1b2...&exp=60min" // 用于下载输出内容的 URL（60 分钟后过期）
}
```

</details>

<details>

<summary>发布商申请事件</summary>

{% hint style="success" %}
**注意：** 此功能目前处于 Beta 阶段。如需测试此功能，请联系您的客户成功经理 (CSM) 或我们的 [支持团队](https://app.impact.com/support/portal.ihtml?createTicket=true&) 。
{% endhint %}

当合作伙伴提交申请，以及每次申请获批、被拒或撤回时，发布商申请事件都会向指定 URL 发送 HTTP 请求。

发布商申请事件也称为合同事件回调、申请处理 webhook 或申请 Webhook。

如果 `PENDING` 载荷在交付时数据点为空，系统会在信息可用后触发更新。后续成功交付时会填充此前为空的字段，确保您的记录与最新处理的信息保持同步。

{% hint style="warning" %}
**重要提示：** 如果您已配置 [申请工作流](https://help.impact.com/brand/zh/what-would-you-like-to-learn-about/platform-features/review-partner-applications/automate-partner-application-processing.md) ，它们会在 webhook 触发前运行。若工作流处理了申请，webhook 触发时的结果 *状态*: `APPROVED` 或 `REJECTED` ；若没有适用的工作流，则为 `PENDING` ；若合作伙伴撤回了申请，则为 `RETRACTED` 。
{% endhint %}

如需了解此 webhook 如何与招聘代理协同工作，请参阅 [招聘代理](https://help.impact.com/brand/zh/what-would-you-like-to-learn-about/platform-features/review-partner-applications/recruitment-agent.md#see-where-the-agent-fits-with-your-existing-automation).

载荷内容因 *状态*而异。以下示例展示了一个 `PENDING` 事件，并通过注释指出其他状态下会出现哪些字段。

```json
// JSON 格式的 POST 示例
{
  "Status": "PENDING", // 申请状态：PENDING、APPROVED、REJECTED、RETRACTED
  "ProgramId": "9876", // 计划 ID
  "TemplateTermsId": "4455", // 模板条款 ID
  "ContractId": "112233", // 合同 ID
  "ApplicationDate": "2026-04-09T08:30:00Z", // 申请日期
  "PublisherSignerName": "Sarah Chen", // 处理此事项的发布商用户
  "PublisherId": "555", // 合作伙伴 ID
  "Name": "Elite Content Creators", // 合作伙伴名称
  "BusinessModel": "SOCIAL_INFLUENCER", // 合作伙伴的主要业务模式
  "Address": "123 Marketing Way", // 街道地址
  "City": "Los Angeles", // 城市
  "State": "CA", // 州
  "Country": "US", // 国家/地区

  // 仅限 APPROVED、REJECTED、RETRACTED
  "DecisionDate": null, // 决策日期

  // 仅限 APPROVED
  "ContractStartDate": null, // 合同开始日期

  // 仅限 REJECTED
  "DeclineReason": null, // 拒绝原因

  // 仅限 APPROVED、REJECTED
  "AdvertiserSignerName": null, // 处理此事项的广告主用户

  // 仅限 PENDING：合作伙伴资料字段
  "Description": "A premium network of lifestyle and travel influencers.", // 合作伙伴资料描述
  "Language": "en-US", // 语言
  "PublisherSize": "M", // XS、S、M、L、XL
  "PastRelationship": "false", // 表示此前是否有过合同关系的布尔值
  "MarketplaceApproved": "true", // 表示市场平台状态的布尔值
  "ReceivedPayout": "true", // 表示是否已收到付款的布尔值

  // 仅限 PENDING：与合作伙伴关联的媒体属性
  "properties": [{join(properties, i, "{\"platform\":\"{i.platform}\",\"verified\":\"{i.verified}\",\"url\":\"{i.url}\",\"category\":\"{i.category}\",\"reach\":\"{i.reach}\",\"engagementRate\":\"{i.engagementRate}\",\"audienceCountryPct\":\"{i.audienceCountryPct}\",\"audienceGenderPct\":\"{i.audienceGenderPct}\",\"audienceAgeRangePct\":\"{i.audienceAgeRangePct}\"}")}],

  // 仅限 PENDING：创作者人口统计信息字段
  "CreatorIncome": "", // 家庭收入
  "CreatorGender": "", // 性别
  "CreatorEthnicity": "", // 族裔
  "CreatorEducation": "", // 教育程度
  "CreatorRelationshipStatus": "", // 感情状况
  "CreatorParentalStatus": "", // 父母身份
  "CreatorPronouns": "", // 人称代词
  "CreatorDOB": "", // 出生日期

  // 仅限 PENDING：群组 ID
  "GroupIds": "1001,1002,1003" // 逗号分隔的群组 ID
}
```

</details>

## Postback 重试机制

如果向目标 URL 发送 postback 时失败，系统会按照预设计划自动重试投递，最多重试 15 次。重试机制有助于应对暂时性的网络问题或服务器不可用的情况。

### 不会重试的情况

出现以下情况时，postback 不会重试：

* 目标 URL 格式错误或无效。
* 目标 URL 或其主机名无法解析，例如 DNS 查找失败。

### 重试计划

重试将按照以下计划进行。如果 HTTP 响应代码介于 `400` 至 `500`.

<details>

<summary>重试计划参考</summary>

<table><thead><tr><th width="180.5390625">重试次数</th><th>重试前的延迟时间</th></tr></thead><tbody><tr><td>重试 1 次</td><td>+15 秒</td></tr><tr><td>重试 2 次</td><td>+15 秒</td></tr><tr><td>重试 3 次</td><td>+15 秒</td></tr><tr><td>重试 4 次</td><td>+3 分钟</td></tr><tr><td>重试 5 次</td><td>+3 分钟</td></tr><tr><td>重试 6 次</td><td>+15 分钟</td></tr><tr><td>重试 7 次</td><td>+15 分钟</td></tr><tr><td>重试 8 次</td><td>+15 分钟</td></tr><tr><td>重试 9 次</td><td>+2 小时</td></tr><tr><td>重试 10 次</td><td>+2 小时</td></tr><tr><td>重试 11 次</td><td>+2 小时</td></tr><tr><td>重试 12 次</td><td>+6 小时</td></tr><tr><td>重试 13 次</td><td>+6 小时</td></tr><tr><td>重试 14 次</td><td>+6 小时</td></tr><tr><td>重试 15 次</td><td>+6 小时</td></tr></tbody></table>

</details>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://help.impact.com/brand/zh/what-would-you-like-to-learn-about/account-administration/account-settings/notifications/enable-event-notification-postbacks-for-brands.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
