什么是API的callback url？在Python中何时以及如何配置使用？

Callback URL（回调地址）本质上是你自己的服务端暴露的、可被第三方API平台公网访问的HTTP接口地址。当第三方平台处理完异步任务（比如支付结果通知、用户授权结果、大文件异步处理结果）之后，会主动向这个地址发送HTTP请求，把处理结果推送给你，不需要你反复轮询调用平台接口查询结果。

• 第三方授权登录场景：比如微信、GitHub OAuth授权，用户在授权页完成操作后，平台会把授权code推送到你填写的callback URL，你拿到code才能兑换access token完成登录流程
• 支付/交易类场景：支付平台处理完用户付款后，会主动把支付成功/失败的结果通知到你的callback URL，你再执行后续的订单状态更新、发货等逻辑
• 异步处理类场景：比如调用AI大模型生成长文本、云平台的音视频转码任务，这类任务处理时间长不会同步返回结果，平台处理完成后就会往你的callback URL推送最终结果

第一步：开发回调接口 #

你可以用任意Python Web框架（Flask、FastAPI、Django等）编写符合第三方平台要求的回调接口，核心要包含验签逻辑，避免收到伪造的恶意通知，以下是Flask框架的简单示例：

from flask import Flask, request, jsonify
import hashlib
import hmac

app = Flask(__name__)
# 替换为API平台给你的专属签名密钥，不要泄露
PLATFORM_SECRET = b"your_platform_secret_here"

@app.route("/api/callback", methods=["POST"])
def platform_callback():
    # 1. 取平台请求的原始内容和请求头里的平台签名
    raw_data = request.get_data()
    platform_sign = request.headers.get("X-Platform-Signature", "")
    
    # 2. 按照平台文档的规则验签，拦截伪造请求
    calculated_sign = hmac.new(PLATFORM_SECRET, raw_data, hashlib.sha256).hexdigest()
    if not hmac.compare_digest(calculated_sign, platform_sign):
        return jsonify({"code": 403, "msg": "签名错误"}), 403
    
    # 3. 解析业务数据，执行你的业务逻辑，比如更新订单状态
    callback_data = request.get_json()
    order_id = callback_data.get("order_id")
    order_status = callback_data.get("status")
    # 此处写你的业务处理逻辑：比如查询数据库更新对应订单状态
    
    # 4. 返回平台要求的固定响应格式，否则平台会判定通知失败反复重试
    return jsonify({"code": 0, "msg": "接收成功"})

if __name__ == "__main__":
    app.run(host="0.0.0.0", port=8000)

第二步：获取公网可访问的回调地址 #

本地开发阶段可以用内网穿透工具（ngrok、frp等）把本地启动的服务端口映射到公网，拿到临时公网地址，比如用ngrok映射本地8000端口后拿到的公网地址是https://xxx-xx-xx-xx.ngrok.io，对应的callback URL就是https://xxx-xx-xx-xx.ngrok.io/api/callback。
生产环境直接使用你的服务绑定的域名+回调接口路径即可，注意必须使用HTTPS协议，绝大多数第三方平台不接受HTTP协议的回调地址。

第三步：在API平台配置回调地址 #

把完整的回调URL填写到API平台对应的配置项即可，部分平台支持调用接口动态配置回调地址，按照平台文档要求传参即可。

注意事项 #

• 回调接口要保证幂等：同一个通知可能因为网络波动被平台多次推送，要做好重复通知的判断逻辑，避免重复执行业务操作（比如重复给用户加余额、重复发货）
• 不要在回调接口里执行耗时逻辑：收到通知后建议先把数据存入数据库，用异步任务处理后续逻辑，避免接口超时导致平台判定通知失败发起重复推送。

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