Webhook Notification

Introduction

This section covers how webhooks are used to notify about events that happen in SmartPay. Some events, like expiry of a card or the automated MIT transactions, are not the result of a direct API request. Webhooks solve these problems by letting you provide a URL to which we will send a notification anytime such an event happens. The "Notification Target URL" will receive a JSON payload depending on the notification type. Based on your integration requirements the notification service has to be turned on. Please contact Customer Support to check your setup configuration.

Authentication Options

Any of the below authentication methods can be selected for the corresponding Merchant key:

Authentication Type	Behavior
No Authentication	No authentication information is sent in the requests to the "Notification Target URL".
Basic Authentication	The authentication is done by specifying a Username and Password under the "Notification Service Settings". These fields are used for basic authentication for every call made to the "Notifications Target URL".

Notification Format

The "Notification Target URL" will receive a JSON payload respecting the below form

Field	Type	Format	Description and example
id	String	UUID	ID of the Subscription Module event triggering the notification: Example: "event-f81c4016-9c74-4046-9079-c00dbe4a5ce2".
createdAt	String	yyyy-MM-dd'T'HH:mm:ss.SS'Z	Time of the creation of the event: Example: "2021-05-26T14:29:05.994Z".
sourceSystem	String	"subscription-module"	-
origin	String	Possible values: api, widget, automated.	Origin triggering the event: an API call, an action performed on the Widget or an event triggered by SmartPay backend.
eventType	String	Enum: created, updated, deleted, status.updated, billing.expires, billing.updated, billing.scheduled.	Description of the event type: created: object creation (e.g subscription, subscription-plan), updated: object amendment (e.g subscription, subscription-plan), deleted: object deletion/cancellation (e.g subscription, subscription-plan), status.updated: subscription, billing-cycle, subscription-plan, payment-series or transaction status change, billing.expires: card used as a payment option is about to expire, billing.updated: this event is triggered whenever the billingAgreement of a subscription is updated, billing.scheduled: this event is created when the merchant configuration is setup to notify the merchant X days before the billing.
objectId	String	UUID	Unique identifier of the object linked to the created event & notification (e.g subscription ID, transaction ID). Example: "subscription-f81c4016-9c74-4046-9079-c00dbe4a5ce2"
objectType	String	Enum: subscription, billing-cycle, subscription-plan, payment-series, transaction manual-retry	Name of the object linked to the created event & notification. Example: "subscription". Please refer to the table below for notification details.
metadata	Dictionary	key, value pairs	Optional object. Additional Ids and details linked to the notification: "metadata": { "reconciliationId": 102957125651 }
context	String	max Length: 10 000	Contains various information used to link the event to a corresponding object. See the table below.
data	Object	-	See table below.

List of the available notifications

objectType	origin	eventType	Description	Format	Data/Context
subscription	api	created	Triggered when Create subscription API is requested.	Based on subscription POST request. When creating the initial event for object creation, the whole request JSON is logged in the "data" property.	Data contains the whole subscription object.
	api	updated	Each PATCH request on the subscription creates an event.	Based on the subscription PATCH request, the "data" property in the event is the request JSON.	Data contains the whole subscription object.
	widget	billing.updated	Each time a billing-agreement is updated on the widget, a new event is created.	Based on billing agreement update.	Data contains the whole subscription object.
	automated	status.updated	An event is created every time the subscription changes its status.	Based on automated status changes which occurred on the subscription.	Data contains the whole subscription object.
	automated	billing.scheduled	The event is created when the merchant configuration is setup to notify the merchant X days before the billing.	Based on merchant settings for "nextBillingDate".	Data contains the whole subscription object.
	automated	billing.expires	Available for Cards only. Event created when the card is about to expire (current month).	Based on a expiry date of the payment object within the subscription, when the billing agreement object has "expiryDate" in it.	Data contains the whole subscription object.
	automated	billing.updated	Every time the "nextBillingDate" is updated, an event is created.	Based on automated "nextBillingDate" changes which occurred on the subscription.	Data contains the whole subscription object.
	api	deleted	Event created when a subscription is canceled immediately.	-	-
billing-cycle	automated	created	Event created when a billing cycle is created.	Based on automated charging which occurred on the billingCycle.	Data contains the whole billingCycle object with context field containing "subscriptionId".
	automated	status.updated	Event created every time the billing cycle changes statuses.	Based on automated changes which occurred on the billingCycle.	Data contains the whole billingCycle object with context field containing "subscriptionId".
	automated	billing.updated	Event created based on updating the billingAgreement within a transaction	-	Data contains the context field containing "subscriptionId".
subscription-plan	api	created	Based on the creation of a subscription plan.	Based on the subscription plan POST request.	Data contains the whole subscriptionPlan object.
	api	updated	Based on the amendment of a subscription plan.	Based on the subscription PATCH request.	Data contains the updated plan as an object.
	api	deleted	Based on the deletion/cancellation of a subscription plan.	-	-
payment-series	api	created	Based on the creation of a payment-series.	Based on the subscription plan POST request, when creating a payment-series, store the whole JSON request.	-
	api	updated	Based on the amendment of a paymentSerie.	Based on the subscription PATCH request. Each PATCH request on the payment-series creates an event.	The "data" property in the event is the request JSON.
	automated	billing.expires	Available for Cards only. Event created when the card is about to expire (current month).	Based on a expiry date of the payment object within the payment-series, notifies merchant when "expiryDate" property for the billing agreement is in the same month.	Data contains the whole subscription object.
	widget	billing.updated	Each time a billing-agreement is updated on the widget, a new event is created.	Based on billing agreement update.	-
	api	deleted	Based on the deletion of a paymentSerie
transaction	automated	created	When a transaction is created via automated processing of billing cycle.	When a transaction is created via automated processing of billing cycle. Created before the transaction is sent to SmartPay.	Context contains billingCycleId, subscriptionId.
	api	created	When a transaction is created via manual-retry	-	Context contains billingCycleId, subscriptionId.
	automated	status.updated	Created when the transaction changes statuses.	When the status of the transaction was updated.	Context contains billingCycleId, subscriptionId.
manual-retry	api	created	Created when a manual retry is performed	-	Context contains the billingCycleId and subscriptionId.