Notifications Overview

Once a webhook has been configured it will immediately begin to receive notifications.

Notifications are sent for most events; each notification has a well defined format. Notifications are all sent in the HTTP body of the request.

Notification Format

Each event contains a number of core properties:

PropertyDescriptionExample
idID of the notificationNOT-3D46-E0EB-47E5-AC7A-10A53C03BF31
domainResource upon which the event occurredInvoice
actionEvent which occurred on the resourcePending
destinationURLURL webhook is being sent to 
entityIDID of the BillForward resourceJSON-encoded value at time notification is created.
This JSON does not include any nested data.
entityIDID of the BillForward resourceJSON-encoded value at time notification is created.
This JSON does not include any nested data.
changesThe fields that changed on this objetJSON-encoded values at time notification is created.
totalSendAttemptsNumber of times the notification was sent 
stateState of notification 

The event is uniquely identified by its domain/action pair.


Use case:

A notification is sent upon an invoice’s being created in the pending state. You can listen for this notification, then apply business logic in response to it.

Example Notification

{
"id" : "NOT-3D46-E0EB-47E5-AC7A-10A53C03BF31",
"domain" : "Invoice",
"action" : "Paid",
"entityID" : "INV-6AE4-2256-4B7A-8C25-650048D15269",
"destinationURL" : "https://app.acme.inc/handle/billforward/webhook",
"format" : "JSON",
"entity" : "{\"id\":\"INV-6AE4-2256-4B7A-8C25-650048D15269\", \"subscriptionID\":\"160EF8D8-916A-48C5-AB86-4726862CEE53\",\"state\":\"Paid\", ... }"
"changes" : "{\"auditFieldChanges\":[{\"attributeName\":\"state\",\"previousValue\":\"Unpaid\",\"newValue\":\"Paid\"}]}",
"totalSendAttempts" : 1,
"state" : "Sent"
}

For example: you could edit the invoice cost, then issue that invoice to the customer.


List of Events

New webhooks are constantly being added to the BillForward API. Because of this, any webhook handling code needs to be made robust, to handle unknown/new events.

Your webhook will automatically respond to state changes on resources. These include (but are not limited to) the following:

`

DomainActionDescription 
SubscriptionProvisionedSubscription in this state has not been activated and no invoices will be raised. 
TrialSubscription has entered a free trial period. 
AwaitingPaymentSubscription has an issued invoice which has not been paid. 
PaidSubscription’s outstanding invoices have all been paid. 
ServiceEndSubscription’s service should be ended when this notification is received. This is a catch-all for Failed, Expired and Cancelled cases. The active flag can be checked as a secondary validation. 
CancelledSubscription was manually cancelled for example by a customer.The ‘subscriptionEnd’ property indicates the end time.
ExpiredSubscription has come a natural end.The ‘subscriptionEnd’ property indicates the end time. For example: end of a non-recurring subscription or fixed-term subscription.
FailedSubscription has failed to pay an invoice during the dunning period.The ‘subscriptionEnd’ property indicates the end time.
InvoicePendingInvoice has not been issued. The invoice can be re-generated and costs changed.
UnpaidInvoice has outstanding cost that has not been paid. 
PaidInvoice has been fully paid with no outstanding cost. 
PaymentFailedInvoice payment from gateway was attempted but failed. 
VoidedInvoice has been voided, this usually occurs when re-calculating an invoice.As invoices are versioned, the old invoice is voided and the new invoice is issued in the desired state.
ReceiptAcceptThe payment gateway allowed the payment request. Generally represents a successful payment
RejectThe payment gateway declined the payment request. Generally represents a failed payment
ErrorAn error occurred submitting payment request to the payment gateway. Refer to reasonCode, rawReasonCode and rawData for further information.
UnknownThe current state of the payment is unknown. Refer to reasonCode, rawReasonCode and rawData for further information.
RefundAwaitingRefundRefund has been created but the payment gateway has not been contacted to perform the refund.
RefundedThe payment gateway allowed the refund request.This means the payment was refunded.
CancelledRefund was manually cancelled.For example: an account may cancel refund before execution.
FailedThe payment gateway declined the refund request. 
FixedTermNeedsAmendmentsInitial state of fixed term
ActiveFixed term is currently running 
ExpiredThe fixed term has ended 
SubscriptionCancellationPendingSubscription has not been cancelled yet
CompletedSubscription has been cancelled 
CancelledThe subscription cancellation has been revoked and the subscription will no longer be cancelled 
PaymentMethodExpiringCard associated with payment method will expire in 1 months time.
ExpiredCard associated with payment method has expired. 

Other notification types

‘Created’ and ‘Updated’ notifications are issued for the following resources:

List of Notification Domains:

Account,
Address,
AdhocSubscription,
Alias,
Amendment,
AmendmentCompoundConstituent,
AmendmentPriceNTime,
APIConfiguration,
AuditLog,
Authority,
AuthorizeNetToken,
BalancedToken,
BraintreeToken,
Card,
Client,
CouponBook,
CouponBookDefinition,
CouponDefinition,
CouponInstance,
CouponInstanceExistingValue,
CouponModifier,
CouponRule,
CreditNote,
CybersourceToken,
DunningLine,
FixedTermDefinition,
FreePaymentReconciliation,
GatewayRevenue,
InvoiceLine,
InvoicePayment,
LocustworldPaymentReconciliation,
Migration,
Notification,
NotificationSnapshot,
Organization,
OrganizationGateway,
Password,
Payment,
PaymentMethod,
PaymentMethodSubscriptionLink,
PaypalSimplePaymentReconciliation,
PaypalToken,
PricingCalculation,
PricingComponent,
PricingComponentTier,
PricingComponentValue,
PricingComponentValueChange,
Product,
ProductRatePlan,
Profile,
Receipt,
Refund,
SearchResult,
StripeToken,
SubscriptionCharge,
TaxationLink,
TaxationStrategy,
TaxLine,
UnitOfMeasure,
Unknown
UsageRoundingStrategies,
User
Username,
Verification,
Webhook

Library Support for Webhook Notifications

SDK support is available for parsing incoming webhooks.

Java

String httpPostBody = ... // get from POST BODY of Notification

Notification notification = NotificationHelper.parse(httpPostBody.toString());

if(notification.getDomain() == NotificationDomain.Invoice &&
notification.getAction() == NotificationAction.Pending) {
InvoiceNotification invoiceNotification = (InvoiceNotification)notification;

Invoice invoice = invoiceNotification.getInvoice();
invoice.issue();
}

Worked Java Notification Handler Example

PHP

$entityBody = file_get_contents('php://input');
print_r($entityBody);

Ruby

// Dependent on library used. For example in a rails controller.
def receives_data
log(request.body.read)
end
Was this article helpful?
YesNo