Webhook Events

Webhooks allow you to subscribe to certain events that happen in Revolv3. When one of these events are triggered we’ll send a HTTP POST payload to the webhook’s configured URL.

Webhooks are configured on a per-merchant basis and we will send you events for every merchant registered in Revolv3.

Events

The available events you will receive are:

Event TypeDescription and TriggersPayload Example
SubscriptionCreatedAn attempt to create subscription was successful.

Triggers when a subscription creation is going to be created using the following end points:

Create Subscription (POST /api/Subscriptions)

Create Customer (POST /api/Customers) when subscriptions are going to be created

Create Subscription (POST /api/Customers/customerId/subscriptions)

Create Checkout (POST /api/Checkout)
{
"EventDateTime": "2023-08-22T21:02:01.9510921Z",
"EventType": "SubscriptionCreated",
"MerchantId": 2,
"RecordId": 1,
"Entropy": "7f64ba26-74db-4cab-8e9c-76a98ba43351"
}
SubscriptionFailedAn attempt to create subscription was unsuccessful.{
"EventDateTime": "2023-08-22T21:02:01.9510921Z",
"EventType": "SubscriptionFailed",
"MerchantId": 2,
"RecordId": 1,
"Entropy": "7f64ba26-74db-4cab-8e9c-76a98ba43351"
}
ACHInvoiceStatusChanged
deprecated - use InvoiceStatusChanged
The webhook is triggered on any status change of an invoice that is going to be paid with ACH payment method. Initial status assignment is NOT considered as “status change”.

Notes:

Please use InvoiceStatusChanged. This Webhook will be deprecated in the future.
{
"EventDateTime": "2023-08-22T21:02:01.9510921Z",
"EventType": "ACHInvoiceStatusChanged",
"MerchantId": 2,
"RecordId": 137,
"Entropy": "7f64ba26-74db-4cab-8e9c-76a98ba43351"
}
InvoiceCreatedThe webhook is triggered when an invoice is created in the system

The event should have InvoiceCreated type

Notes:
one-time payment invoices
recurrent payment invoices
installments payment invoices
{
"EventDateTime": "2023-08-22T21:01:01.9510921Z",
"EventType": "InvoiceCreated",
"MerchantId": 2,
"RecordId": 137,
"Entropy": "7f64ba26-74db-4cab-8e9c-76a98ba43351"
}
InvoiceStatusChangedThe webhook is triggered on any status change of an invoice. Initial status assignment is NOT considered as “status change”.

Notes:

status of the invoice can be changed by Update Invoice request (Update an invoice by invoice Id that is currently in the 'Pending' or 'Recycle' state)

webhook should be triggered for Refund invoices as well (incl. changes from Pending to Refund / PartialRefund / RefundPending / RefundDeclined / RefundFailed statuses)

webook should be triggered for one time payments and recurrent invoices
{
"EventDateTime": "2023-08-22T21:02:01.9510921Z",
"EventType": "InvoiceStatusChanged",
"MerchantId": 2,
"RecordId": 137,
"Entropy": "7f64ba26-74db-4cab-8e9c-76a98ba43351"
}
InvoiceAttemptCreated
(RecordId is InvoiceId)
The webhook is triggered when an invoice attempt is created in the system

Notes:

incl.

one-time payment invoices

recurrent payment invoices

installments payment invoices
{
"EventDateTime": "2023-08-22T21:02:01.9510921Z",
"EventType": "InvoiceAttemptCreated",
"MerchantId": 2,
"RecordId": 137,
"Entropy": "7f64ba26-74db-4cab-8e9c-76a98ba43351"
}
InvoiceAttemptStatusChanged
(RecordId is InvoiceId)
The webhook is triggered on any status change of an invoice attempt. Initial status assignment is NOT considered as “status change”.

Notes:

webhook should be triggered for Refund invoices as well (incl. changes from Pending to Refund / PartialRefund / RefundPending / RefundDeclined / RefundFailed statuses)

webook should be triggered for one time payments and recurrent (subscription or installment) invoices
{
"EventDateTime": "2023-08-22T21:02:01.9510921Z",
"EventType": "InvoiceAttemptStatusChanged",
"MerchantId": 2,
"RecordId": 137,
"Entropy": "7f64ba26-74db-4cab-8e9c-76a98ba43351"
}
WebhookTest{
"EventDateTime": "2023-08-31T13:30:22.8938167Z",
"EventType": "WebhookTest",
"MerchantId": 2147483647,
"RecordId": 2147483647,
"Entropy": "d1153029-c1a9-4497-b1e8-10111751fece"
}

Each Event will consist of:

EventDateTimeThe date and time that event occurred (UTC time)
EventTypeThe type of event of that occurred (see the table above)
MerchantIdThe ID of the merchant that the event happened in
RecordIdThe ID of the resource that has changed (Invoice, Subscribtion, etc…)
EntropyA random string to make the payload more cryptographically secure

The x-revolv3-signature header

A hashed signature of the payload is passed along in the headers of each request as x-revolv3-signature. This signature is used to be sure all requests are sent from revolv3 application.

We are using HMACSHA256 algorithm to generate the signature key.

Example of how to check on C#

public static bool IsValidWebhookEventSignature(  
        string requestBody,  
        string signatureHeader,  
        string signatureKey,  
        string url)  
{  
  //url is where the webhook is being sent to and includes https example: "https://webhook.site/462a579b-1cb2-4ae4-b4de-631fad16b3dd"
	if (string.IsNullOrEmpty(signatureKey))  
		throw new ArgumentNullException(nameof (signatureKey));  
	if (string.IsNullOrEmpty(url))  
		throw new ArgumentNullException(nameof (url));  
	byte[] bytes = Encoding.UTF8.GetBytes(url + "$" + requestBody); //Concat strings with a $  
	using var hmacshA256 = new HMACSHA256(Encoding.UTF8.GetBytes(signatureKey));  
	return Convert.ToBase64String(hmacshA256.ComputeHash(bytes)).Equals(signatureHeader);  
}


function IsValidWebhookEventSignature(string $requestBody, string $signatureHeader, string $signatureKey, string $url): bool
{
  // Check for empty arguments
  if (empty($signatureKey)) {
    throw new ArgumentNullException('signatureKey');
  }
  if (empty($url)) {
    throw new ArgumentNullException('url');
  }

  // Concatenate url and request body with a delimiter
  $data = $url . '$' . $requestBody;

  // Create HMAC object with SHA256 algorithm
  $hmac = hash_hmac('sha256', $data, $signatureKey, true);

  // Encode the HMAC hash to base64 and compare with signature
  return base64_encode($hmac) === $signatureHeader;
}


Creating a webhook
To create a webhook for your merchant you have to go to Webhooks page and create a new webhook.

You have to specify:

The url for us to deliver to.

You have to copy your Webhook Key and prepare your backend to receive the webhooks.

If your app is ready to receive webhooks, click on the Test Connection button. In case we receive a response with code 200 the Save button will be enabled. After you save the configuration everything is ready to receive information