Webhooks overview

Webhooks are a way to customize your software with real time updates from Partial.ly. Partial.ly can send any URL you specify details when specific events occur, such as a payment plan being opened, payment succeeded, or a payment fails.
Webhooks will post a JSON formatted document to your URL. To verify that the webhook is coming from Partial.ly, and that the data has not been tampered with, Partial.ly will also add the Partially-Signature header to the webhook request. The value of this header will be the sha-256 HMAC of the posted body, using your your API key as the secret key. Your API key can be found in your Partial.ly merchant portal by going to Settings and then general.

Configuring webhooks

To add a webhook, log in to the Partial.ly merchant portal, click Settings, then webhooks.


You can also test your webhook by sending fake events using the webhook testing tool, by clicking the Test webhooks link on the webhook settings page. This will send a test webhook to the URL you provide, and display the request and response bodies.


Webhook format

All webhooks will have the following keys:

  • event - the type of event
  • id - the id of the event
  • data - data specific to the event

The following events are currently supported:

  • plan_opened - sent when a new payment plan is opened
  • payment_succeeded - sent when a scheduled payment is successful
  • payment_failed - sent when a scheduled payment fails
  • plan_paid - sent when a payment plan is fully paid
  • plan_defaulted - sent when a payment plan defaults due to 3 consecutive failed payments
  • plan_canceled - sent when a payment plan is canceled
  • dispute_created - sent when a customer disputes a payment
  • dispute_closed - sent when a customer dispute has been resolved, either won or lost
  • refund_created - sent when a customer payment is refunded


Failed webhooks will be automatically retried each hour, up to 20 times. If we're unable to successfully send a webhook after 20 tries, your webhook will automatically be disabled. You can re-enable it from your webhook settings in the future.