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 Name	Data Type	Comments
`uuid`	String	A unique ID that can be used to track the messages you've processed.
`created_at`	Date	The timestamp of the webhook request.
`event`	String	The type of event that prompted the webhook call. An example is "payment_term.accepted".
`entity`	JSON	A JSON representation of the subject of the webhook notification (Invoice, Order, or Payment Term).
`status`	String	The current status of the item being updated.
`links`	URL	The 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:

The signature itself. This can be found in the X-Apruve-Signature HTTP header included in every Apruve webhook request.
Apruve's public key. You can get this value interactively via Apruve's Public Key API.
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.