跳转到主要内容
1签 (OneSign)

C SDK:验证通知与返回回执

本页内容

在 C 接收端验证通知来源,保存业务处理结果,再向平台返回回执。

适用场景

在 C 服务接收平台事件时,先验证原始报文,再持久保存事件或业务结果,最后返回接收回执。SDK 提供验签和回执函数,HTTP 接收与数据库事务仍由您的服务负责。

只想验证报文可运行 verify 模式;验证接收地址用 challenge 模式。接入真实业务时,不能把命令行验证成功当作业务已经保存。

前提条件

  • 已创建自己的订阅,并保存回调专用 CSW 密钥、完整 WHK 订阅 ID、绑定应用 ID、通知来源与所选事件。
  • HTTP 层保留原始正文和四个签名头,先拒绝重复签名头,再交给 SDK 验证。不要把解析或格式化后的 JSON 用来验签。
  • 接收端时钟同步,准备按订阅与事件 ID 去重的持久存储。回调密钥不是 AccessKey Secret。

操作步骤

  1. 从自己的受信订阅配置取得密钥,填写 cloudsign_webhook_options,不能用传入值覆盖预期订阅或应用。
  2. 将原始正文和四个请求头放入 cloudsign_webhook_request,调用 cloudsign_webhook_verify;输出事件指针先设为 NULL。
  3. 使用 cloudsign_webhook_is_challenge 区分地址验证。普通事件还需按受信配置核对来源和所选事件,再在持久事务中去重并保存。
  4. 挑战验签成功后,或普通事件事务提交成功后,调用 cloudsign_webhook_acknowledge 生成 JSON 回执并由 HTTP 层发送。
  5. 处理完成后调用 cloudsign_webhook_event_free,不要继续使用事件内部的指针。

运行示例

示例将受信订阅配置和本次投递头分开读取,具体变量见下表。真实 HTTP 服务直接填写结构体。raw-body.json 保留收到的原始字节,不从格式化输出复制。

命令行示例需要哪些配置

这些变量由自己的进程安全配置注入,不把 Secret 写进命令历史或源码。它们只配置客户端,不选择平台存储厂商。

变量如何填写
CLOUDSIGN_WEBHOOK_SECRET受信订阅的独立回调密钥。
CLOUDSIGN_WEBHOOK_ID受信订阅的完整 WHK 标识。
CLOUDSIGN_WEBHOOK_APP_ID订阅绑定的业务应用 ID。
CLOUDSIGN_DELIVERY_WEBHOOK_ID本次 X-Cloudsign-Webhook-Id 请求头。
CLOUDSIGN_DELIVERY_EVENT_ID本次 X-Cloudsign-Event-Id 请求头。
CLOUDSIGN_DELIVERY_TIMESTAMP本次 X-Cloudsign-Timestamp 请求头。
CLOUDSIGN_DELIVERY_SIGNATURE本次 X-Cloudsign-Signature 请求头。
构建并运行示例
cmake -S . -B build
cmake --build build -j2
# raw-body.json 保留收到的原始字节。
./build/cloudsign_webhook_example verify raw-body.json
# 仅对 endpoint.challenge 生成回执。
./build/cloudsign_webhook_example challenge raw-body.json
查看完整 webhook-example.c 源码
C11 · webhook-example.c
/* Offline verifier. It never sends HTTP or acknowledges business events. */
#include <cloudsign/openapi.h>
#include <openssl/crypto.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>

int main(int argc,char **argv) {
    cloudsign_webhook_event *event=NULL;unsigned char body[CLOUDSIGN_WEBHOOK_BODY_LIMIT+1]={0};
    char secret[48]={0},receipt[CLOUDSIGN_WEBHOOK_ACK_CAPACITY]={0};
    cloudsign_status status=CLOUDSIGN_INVALID_INPUT;FILE *file=NULL;int exit_code=1;
    int verify=argc==3&&!strcmp(argv[1],"verify"),challenge=argc==3&&!strcmp(argv[1],"challenge");
    if(!verify&&!challenge){fputs("Usage: cloudsign_webhook_example verify|challenge RAW_BODY_FILE\n",stderr);goto done;}
    const char *configured=getenv("CLOUDSIGN_WEBHOOK_SECRET");
    if(!configured||strlen(configured)>=sizeof(secret))goto done;
    memcpy(secret,configured,strlen(configured)+1);
    file=fopen(argv[2],"rb");
    if(!file||fseek(file,0,SEEK_END))goto done;
    long length=ftell(file);
    if(length<=0||length>(long)CLOUDSIGN_WEBHOOK_BODY_LIMIT||fseek(file,0,SEEK_SET))goto done;
    if(fread(body,1,(size_t)length,file)!=(size_t)length||ferror(file))goto done;
    fclose(file);file=NULL;
    /* Trusted subscription configuration and untrusted delivery headers are
     * deliberately separate. A server HTTP adapter must reject duplicates. */
    cloudsign_webhook_options options={secret,getenv("CLOUDSIGN_WEBHOOK_ID"),getenv("CLOUDSIGN_WEBHOOK_APP_ID")};
    cloudsign_webhook_request request={getenv("CLOUDSIGN_DELIVERY_WEBHOOK_ID"),getenv("CLOUDSIGN_DELIVERY_EVENT_ID"),getenv("CLOUDSIGN_DELIVERY_TIMESTAMP"),getenv("CLOUDSIGN_DELIVERY_SIGNATURE"),body,(size_t)length};
    status=cloudsign_webhook_verify(&options,&request,&event);
    OPENSSL_cleanse(secret,sizeof(secret));OPENSSL_cleanse(body,sizeof(body));
    if(status!=CLOUDSIGN_OK)goto done;
    if(verify){printf("%s %s\n",cloudsign_webhook_event_id(event),cloudsign_webhook_type(event));exit_code=0;goto done;}
    if(!cloudsign_webhook_is_challenge(event)){
        fputs("Business events require a durable commit before acknowledgment.\n",stderr);exit_code=2;goto done;
    }
    status=cloudsign_webhook_acknowledge(event,receipt,sizeof(receipt));
    if(status==CLOUDSIGN_OK){puts(receipt);exit_code=0;}
done:
    if(exit_code==1)fprintf(stderr,"%s\n",cloudsign_status_name(status));
    if(file)fclose(file);
    cloudsign_webhook_event_free(event);OPENSSL_cleanse(secret,sizeof(secret));
    OPENSSL_cleanse(body,sizeof(body));OPENSSL_cleanse(receipt,sizeof(receipt));return exit_code;
}

确认结果

情况怎样判断下一步
verify 退出 0报文与受信配置匹配。这里只输出事件 ID 和类型,业务仍需单独持久保存。
challenge 退出 0已验证挑战并生成 challenge、proof 回执。由 HTTP 服务返回该 JSON 与正确 Content-Type。
普通业务事件退出 2challenge 演示拒绝代替业务事务确认。接入自己的持久事务后再生成普通回执。
退出 1 / InvalidWebhook配置或通知验证失败。返回非 2xx,不输出成功回执。

验签成功不等于业务处理成功。普通回执只在事务已提交,或确认同一事件此前已经提交时返回。

参数与详细规则

区分受信配置与本次投递数据。来源由您保存的订阅配置决定,不能仅凭事件名称推断。

参数或对象表示什么使用要点
webhook_options自己保存的回调密钥、订阅与绑定应用。不从收到的正文任意选择密钥。
webhook_request四个投递头和原始正文指针、字节数。SDK 验证前不改写正文。
event / acknowledge已验证事件及其 JSON 回执。生成回执不会替您的服务提交数据库事务或发送 HTTP。
查看完整参数、内存管理与运行边界
结构或函数填写与结果
cloudsign_webhook_options可信的 secret、webhook_id、app_id;使用回调专用 CSW 密钥,不使用 AccessKey Secret。
cloudsign_webhook_request四个请求头依次为 webhook_id、event_id、timestamp、signature;另传 body 指针与实际字节数 body_length。
cloudsign_webhook_verify输出指针先置 NULL。验证成功返回 OK 及事件;格式、过期、篡改或归属错误统一返回 InvalidWebhook,不返回正文。内存 / 本机配置错误另有状态。
cloudsign_webhook_json / json_length返回 SDK 自有的已验证原始正文副本及长度。调用方可在 verify 返回后释放 HTTP 输入;getter 借用数据仅在 event_free 前有效。
cloudsign_webhook_acknowledge只对已验证事件生成 JSON,不发送 HTTP、不去重、不提交业务。缓冲区使用 CLOUDSIGN_WEBHOOK_ACK_CAPACITY(256 字节),失败不返回部分回执。
cloudsign_webhook_event_free每条成功事件处理完都释放;可传 NULL。同一事件或输入不可同时修改 / 释放,线程间的业务去重由接收服务负责。

普通事件:在同一个持久事务中按 (webhook_id, event_id) 唯一键去重并保存业务结果,提交成功后才调用 acknowledge,返回 HTTP 2xx、Content-Type: application/json 和生成的 JSON 回执。重复事件只有在查到先前事务已提交时才确认;事务失败则返回非 2xx,让平台按策略重投。验签成功不等于业务处理成功。SDK 不会代替数据库去重,也不会阻止同一个合法事件再次验签。

挑战事件:用 cloudsign_webhook_is_challenge 区分,验证后可直接生成含 challenge 与密钥 proof 的回执;没有业务 app_id,app getter 返回空串,但配置仍需填写订阅绑定的 应用 ID。财务金额保持两位小数的字符串,禁止转为二进制浮点;通知可能乱序,以 签名任务 ID / 上传任务 ID / 版本 ID / 订单 ID 对应接口的最新结果为准。created_at 是事件创建时间,不用它代替四个头中的投递时间。

失败后如何继续

情况怎样判断下一步
重复事件同一事件 ID 再次到达,投递时间和签名可能变化。每次重新验签,查到既有事务已提交后再确认。
保存失败业务事件未成功持久保存。回滚并返回非 2xx,等待平台按规则重投。
通知顺序与当前状态不同事件可能乱序,created_at 不是本次投递时间。查询对应原任务、版本或订单,避免旧通知覆盖新状态。

SDK 校验原始正文 1–8192 字节和投递时间前后 300 秒。回执缓冲使用 CLOUDSIGN_WEBHOOK_ACK_CAPACITY。新建订阅、更换回调配置后按开发者中心完成地址验证;通知字段与重投规则见 报文与回执参考。