同步

介绍

创建和管理订阅后,您可能需要一种让应用程序了解客户订阅状态的方法。可以直接通过API或通过Chargify方便地通知您的应用程序来完成此操作 网络挂钩 feature.


允许或通知您的应用程序有关客户订阅状态的三种基本方法:

API

最简单的方法之一就是让您的应用程序使用API​​请求订阅的当前状态(或历史记录)。这将在请求时提供订阅的当前状态。

订阅状态

要获取订阅的当前状态,方法如下所示:

HTTP GET //{subdomain}.ikvrej.icu/subscriptions/{subscription_id}.{format}

您将收到有关订阅的所有当前信息,包括(但不限于):

  • 订阅详细信息(订阅状态,创建,余额,下次评估日期,取消信息等)。
  • 顾客信息
  • 付款详情

有关更多详细信息,请参阅以下文档中的API文档: 阅读订阅.

最佳实践

以下是我们建议的有关使用API​​以及如何将应用程序与Chargify数据同步的一些最佳实践:

  1. 您的应用程序应尝试而不依赖其他服务直接控制访问。如果您的API调用由于某种原因而失败,则您的客户可能无法获得最佳的用户体验,具体取决于您的实现方式。
  2. 如果可能(和何时),您应该尝试限制对Chargify的直接调用,因为对Chargify API响应非常快速和大量API调用的速度(和频率)有限制。有关更多信息,请参见 限制和限制.

网络挂钩

网络挂钩提供了一种快速查找关于Chargify中发生的订阅更改的方法。您可以订阅感兴趣的事件,并且当这些事件之一发生时,我们会将数据发布到您指定的URL。

有关更多常规信息,请参见 网络挂钩.

使用Webhooks

要开始使用Webhook,必须首先创建一个具有以下特征的可公开访问的端点:

  1. 我们仅在测试模式下才允许HTTP端点。您必须先切换到HTTPS,然后才能进入实时模式。
  2. 您提供给Chargify的端点必须在端口80或443上,这是唯一受支持的端口。
  3. 您的端点必须接受带有表单编码的正文的HTTP POST请求到您的URL。

Once you have a public URL which Chargify can attempt to send data to, then you can begin accepting requests and sending the expected 200 OK response.

通常,使用Webhooks的正常过程是:

  1. 在Chargify,发生了您的Webhook URL订阅事件。例如,新客户已经在您的网站上注册-创建新的订阅。
  2. 在某些时候,Chargify向您的Webhook URL发出请求,其中包含注册事件数据。
  3. 您收到注册事件数据。
  4. 您验证注册事件数据(使用签名验证)。
  5. 您可以使用经过验证的事件数据执行一些操作,例如向客户发送欢迎电子邮件或提供服务。
  6. You respond 200 OK to the initial request, thereby completing the webhook transaction with Chargify.

请参阅 网络挂钩 文档以获取更多信息。

配置Webhooks

网络挂钩是一种简单的方法,它允许Chargify系统直接与您的用户“交谈”,而不是让系统轮询Chargify来始终获取最新信息。

在您的Chargify帐户中配置的Webhooks非常简单:

您可以根据需要启用/禁用webhook,虽然不需要使用它们,但它们确实有很大的好处。

请参阅 配置webhooks 文档以获取更多信息。

测试Webhook

对于初始测试,可以使用许多选项。

Before you have a publicly accessible endpoint available, or if you just are looking at webhook for troubleshooting - we suggest using a tool like //requestbin.fullcontact.com/. Requestbin provides a temporary URL that Chargify may send messages to, allowing you to view them easily within their application. The “bins” are temporary. This can provide quick insight into the content or headers Chargify will be sending.

Chargify的webhook功能提供了一种测试方法,该方法将向您指定的任何单个webhook URL发送一条简单消息。该测试消息对于验证URL和Chargify之间的连接性非常有用,

接收Webhook通知

要启用对Webhooks的接收,只需从您的站点设置中启用它们-选择端点应接收的事件。以下是测试Webhook接收和入门的良好流程:

  1. 设置可公开访问的Webhook处理程序
  2. Enable webhooks at that endpoint, enable events you need to interact with (at the very least subscription_state_change, triggered when subscriptions move from active to cancelled)
  3. 发送测试事件
  4. 检查您的签名验证码,确认您正在响应 200 OK
  5. 添加您需要的特定事件处理代码

响应Webhook

Upon receipt of a webhook, you should accept it by returning an HTTP 200 OK response as quickly as possible. Sending any other response (i.e. 500 Internal Server Error, 404 Not Found, etc.) OR failing to return a response within approximately 15 seconds will result in automatic retries of the webhooks.

有关重试机制和webhook重播的更多详细信息,请参见我们的 文件资料.

验证事件

通过使用共享密钥作为秘密,对Webhook帖子的原始HTTP正文进行HMAC-SHA-256十六进制摘要生成的签名对Webhooks进行签名。

例如,在Ruby中: ruby OpenSSL::HMAC.hexdigest(OpenSSL::Digest.new('sha256'), site.shared_key, webhook.body)

为了验证事件,您将需要执行签名验证-即验证请求中包含的签名与给定要交付的内容所期望的签名完全匹配。

You may either retrieve the signature value through the header X-Chargify-Webhook-Signature-Hmac-Sha-256 or by specifying that the signature should be included in the query string by using the {signature_hmac_sha_256} replacement variable:

http://example.com/?signature={signature_hmac_sha_256}

请参阅 webhook签名验证 欲获得更多信息。

最佳实践

以下是我们建议的有关Webhooks的一些最佳做法:

  • 网络挂钩是 异步事件。我们会尽力始终将它们及时发送给我们,但是我们 不要 建议依靠webhooks进行对时间敏感的事件。
  • 我们 不要 建议您根据Webhook响应阻止用户继续进行配给或注册。适当的方法是查询订阅API以验证订阅。

下一步