Webhooks

You can receive automated notifications of events in Apruve via webhooks.

How Apruve Uses Webhooks

When a webhook_url is specified on a Merchant's profile, Apruve will POST a JSON document to that URL when the status of an item changes. Apruve expects a 200 response from this POST. If a 200 is not received, we will keep trying (with exponentially increasing delay) for 24 hours.

The status changes that will trigger a Webhook call are:

  • Invoice Closed
  • Invoice Funded
  • Invoice Canceled
  • Order Accepted
  • Order Canceled
  • Payment Term Accepted
  • Shipment Created
  • Shipment Updated
  • Corporate Account Approved
  • Team Member Added
  • Team Member Removed
  • Credit Available Updated

The JSON payload will contain the following information:

Field NameData TypeComments
uuidStringA unique ID that can be used to track the messages you've processed.
created_atDateThe timestamp of the webhook request.
eventStringThe type of event that prompted the webhook call. An example is "payment_term.accepted".
entityJSONA JSON representation of the subject of the webhook notification (Invoice, Order, or Payment Term).
statusStringThe current status of the item being updated.
linksURLThe URL for the item from the Apruve API. This URL may be used as a unique identifier for the resource, and/or to fetch the item from the API.

Example Webhook Payload:

{
    "uuid":"abcdefghi",
    "created_at":"2016-08-18T10:36:54-05:00",
    "event":"payment_term.accepted",
    "entity": 
    {
        "po_number":"abcdefghi",
        "type":"CorporateAccount",
        "status":"approved",
        "escalated_at":null,
        "final_state_at":null,
        "links":
        {
            "order":"https://test.apruve.com/api/v4/orders/jklmnopqr"
        }
    }
}

Each Webhook has a unique UUID that identifies it. If you have trouble with a Webhook, this would be helpful information to include in a support request.

Digital Signature

Every Apruve webhook contains a SHA256/RSA digital signature of the webhook's contents. If the signature can be verified
using Apruve's public key, you can be certain that the webhook contents were generated by Apruve and have not been
tampered with. To verify a webhook, you need the following three pieces of information:

  1. The signature itself. This can be found in the X-Apruve-Signature HTTP header included in every Apruve webhook request.
  2. Apruve's public key. You can get this value interactively via Apruve's Public Key API.
  3. The raw, unparsed body of the webhook.

The specific procedure for verifying the signature will vary based on your platform's underlying technology. If your platform
does not provide libraries that provide signature verification services, OpenSSL provides command line tools that can.

Ruby Example:

apruve_public_key = OpenSSL::PKey.read(Apruve::Client.get('public_key.txt').body)
verified = apruve_public_key.verify(
                  OpenSSL::Digest::SHA256.new,
                  Base64.decode64(webhook.headers['X-Apruve-Signature']),
                  webhook.body)

Apruve Webhook Best Practices

To promote the best security in your Apruve webhook notification service, we recommend following these best practices:

  • Use SSL/HTTPS in the URL you provide for your webhook service.
  • Verify the request signature.
  • Create a mechanism to guarantee that only Apruve will know the correct URL. Perhaps the best way to do this would be to generate a long, random token (sometimes referred to as an API-key, GUID, or UUID) that is specified as part of the callback URL you provide to Apruve. When you receive the webhook POST, you should authenticate this token and verify that it is valid.
  • You can also query Apruve using the api_url and verify that the status is correct, rather than trusting the data you receive on the webhook call. For the absolute highest level of security, use the api_url that you received in the HTTP response when you created the original payment.

Taking these steps will ensure that only Apruve is authenticated and authorized to trigger a status update in your system.

Webhooks

Webhook - invoice.closed

Overview

This webhook event is sent to your webhook endpoint when an invoice is closed. The entire invoice is sent as the payload in this webhook. Once an invoice is closed, it has been paid. If you have been waiting for payment before you deliver, now would be the time to trigger that.

See the example webhook payload above.

Webhook - invoice.funded

Overview

This webhook event is sent to your webhook endpoint when an invoice is funded. The entire invoice is sent as the payload in this webhook. Once an invoice is funded, the merchant has been paid out, and the creditor is expecting payment. No further action should be necessary by the merchant.

See the example webhook payload above.

Webhook - invoice.canceled

Overview

This webhook event is sent to your webhook endpoint when an invoice is canceled. The entire invoice is sent as the payload in this webhook. Once an invoice is canceled, it has been withdrawn by the merchant.

See the example webhook payload above.

Webhook - order.accepted

Overview

This webhook event is sent to your webhook endpoint when an order is accepted. The entire order is sent as the payload in this webhook. For many situations, order Acceptance is the event to be used to decide when to ship a product or deliver a service.

See the example webhook payload above.

Webhook - order.canceled

Overview

This webhook event is sent to your webhook endpoint when an order is canceled. The entire order is sent as the payload in this webhook. If an order is canceled, it should not be delivered as no payment will be possible.

See the example webhook payload above.

Webhook - payment_term.accepted

Overview

(deprecated) This webhook event is sent to your webhook endpoint when a payment_term is accepted. The entire payment_term is sent as the payload in this webhook.
Once a payment_term is accepted, that means that a contract for payment is established, in most industries this would trigger fulfillment of your product.

See the example webhook payload above.

Webhook - shipment.created

Overview

This webhook event is sent to your webhook endpoint when a shipment is created. The entire shipment is sent
as the payload in this webhook. A shipment is always associated with an invoice, and may contain all or some of the items
from the invoice that have been shipped. A shipment which fulfills all invoice totals will be in a 'fulfilled' status,
while a partial shipment will return a 'partial' status.

See the example webhook payload above.

Webhook - shipment.updated

Overview

This webhook event is sent to your webhook endpoint when a shipment is updated. The entire shipment is sent
as the payload in this webhook. An updated shipment may contain an updated tracking number, shipping_cents amount or
status as indicated by which subset of invoice items have been fulfilled.

See the example webhook payload above.

Webhook - corporate_account.approved

Overview

This webhook event is sent to your webhook endpoint when a corporate account is approved with a credit limit. The entire corporate account is sent as the payload in this webhook.

See the example webhook payload above.

Webhook - team_member.added

Overview

This webhook event is sent to your webhook endpoint when a team member is added to one of your corporate accounts.
Information about the team member, including their roles and the uuid of their corporate account, is sent with this webhook.

See the example webhook payload above.

Webhook - team_member.removed

Overview

This webhook event is sent to your webhook endpoint when a team member is removed fromone of your corporate accounts.
Information about the team member, including their roles and the uuid of their corporate account, is sent with this webhook.

See the example webhook payload above.

Webhook - credit_limit.updated

Overview

This webhook event is sent to your webhook endpoint when the available credit is updated.
Information about the credit limit and corporate account is sent with this webhook.

See the example webhook payload above.