求Smartsheet回调的C# WebApi控制器方法示例及参数说明

我刚好做过类似的Smartsheet WebHook集成，给你梳理一下具体的实现细节和负载说明，应该能帮你解决问题：

1. 回调控制器方法示例 #

推荐方案：强类型接收负载（更易维护） #

这种方式比直接接收字符串更规范，也方便后续处理数据。首先你需要定义和Smartsheet回调负载对应的模型类（可以根据实际需要调整字段，下面是核心字段示例）：

using Newtonsoft.Json;

public class SmartsheetWebhookPayload
{
    [JsonProperty("webhookId")]
    public long WebhookId { get; set; }

    [JsonProperty("timestamp")]
    public long Timestamp { get; set; }

    [JsonProperty("userId")]
    public long UserId { get; set; }

    [JsonProperty("eventType")]
    public string EventType { get; set; }

    [JsonProperty("data")]
    public WebhookData Data { get; set; }
}

public class WebhookData
{
    [JsonProperty("sheetId")]
    public long SheetId { get; set; }

    [JsonProperty("changedCells")]
    public List<ChangedCell> ChangedCells { get; set; }
}

public class ChangedCell
{
    [JsonProperty("rowId")]
    public long RowId { get; set; }

    [JsonProperty("columnId")]
    public long ColumnId { get; set; }

    [JsonProperty("newValue")]
    public object NewValue { get; set; }

    [JsonProperty("oldValue")]
    public object OldValue { get; set; }
}

然后在你的WebAPI控制器中编写回调方法：

using System.Web.Http;

public class SmartsheetWebhookController : ApiController
{
    // Smartsheet WebHook默认会用POST请求发送回调，所以用HttpPost特性
    [HttpPost]
    public IHttpActionResult ReceiveWebhook([FromBody] SmartsheetWebhookPayload payload)
    {
        if (payload == null)
        {
            return BadRequest("Invalid payload received");
        }

        // 这里处理你的业务逻辑，比如记录日志、更新本地数据等
        // 示例：打印关键信息
        System.Diagnostics.Debug.WriteLine($"WebHook触发，事件类型：{payload.EventType}，表格ID：{payload.Data.SheetId}");

        // Smartsheet要求回调返回200状态码确认接收，否则会重试
        return Ok();
    }
}

备选方案：直接接收字符串负载 #

如果你暂时不想定义模型，也可以直接接收字符串，参数命名没有强制要求，只要标记[FromBody]即可：

[HttpPost]
public IHttpActionResult ReceiveWebhook([FromBody] string payload)
{
    if (string.IsNullOrEmpty(payload))
    {
        return BadRequest("Empty payload received");
    }

    // 手动解析JSON字符串
    // 示例：用Newtonsoft.Json解析
    var payloadObj = JsonConvert.DeserializeObject<SmartsheetWebhookPayload>(payload);
    
    // 业务逻辑处理...
    
    return Ok();
}

2. 负载参数的类型与命名说明 #

Smartsheet WebHook的回调负载是JSON格式，核心字段说明如下：

• webhookId（long）：触发回调的WebHook唯一ID
• timestamp（long）：事件发生的Unix时间戳（毫秒）
• userId（long）：触发数据变更的用户ID
• eventType（string）：事件类型，比如Sheet.Row.Created、Sheet.Row.Updated、Sheet.Cell.Updated等
• data（object）：包含具体变更数据的对象，不同事件类型的data结构会略有差异：
  • 单元格变更事件（Sheet.Cell.Updated）会包含changedCells数组，每个元素包含rowId、columnId、newValue、oldValue
  • 行新增/删除事件会包含rowIds数组

简化的负载示例：

{
  "webhookId": 123456789,
  "timestamp": 1690000000000,
  "userId": 987654321,
  "eventType": "Sheet.Cell.Updated",
  "data": {
    "sheetId": 112233445,
    "changedCells": [
      {
        "rowId": 556677889,
        "columnId": 998877665,
        "newValue": "Updated Value",
        "oldValue": "Original Value"
      }
    ]
  }
}

关于参数命名：

• 如果你用强类型接收，模型字段名可以和JSON键不一致，只要通过[JsonProperty("json键名")]映射即可
• 直接接收字符串的话，参数名称完全不影响，因为Smartsheet会把整个JSON作为请求体发送

内容的提问来源于stack exchange，提问作者HiTechRedNeck