Webhooks

Setting up webhooks

Your webhooks configuration is set up by the following :

• notifyUrl :

  • your endpoint used to post notifications to
  • either specified by default on your platform, or specified by you during an Order creation

• webhookSecretKey :

  • is used to generate the SG-Signature headers to be matched
  • can be retrieved on your Dashboard > Platform > Credentials > webhook secret key

The list of events needed for your integration is currently configured on your platform by ShareGroop

TIP

You can ask us for our IPs if you shall whitelist them.

Webhook signatures

A webhook signature is a security measure which allows you to verify the integrity and authenticity of the data you’re receiving. Each webhook contains a hash-based message authentication code (HMAC) in its SG-Signature header. ShareGroop generates the HMAC by taking the contents of the webhook notification and hashing it using the webhook secret key as the key.

Using signatures is simple. All you need to do is take the webhook's body and apply the SHA-256 hash function to it, using the secret key as the hash key. You then compare the resulting HMAC to the one contained in the SG-Signature header (without the 'v1='). If the HMACs are identical, then the data corresponds to what ShareGroop sent. If they are different, this indicates that the data has been intercepted and altered in some way.

Attention

When you need to generate the HMAC for comparison, you must use the raw body of the request because the ordering of its properties matters too.

Example code to check the signature:

// nodejs module crypto
const crypto = require('crypto');

// your platform webhook secret key
const YOUR_WEBHOOK_SECRET_KEY = 'thisisasecret';

// hmac function
const getHmac = (content, secret) =>
	crypto
		.createHmac('sha256', secret)
		.update(content, 'utf8')
		.digest('hex');

// the event received on your endpoint
const eventReceived = {
	payload: {
		event: 'order.completed',
		id: 'ord_seed1',
		date: 1567430953297,
	},
	headers: {
		'Content-Type': 'application/json',
		'SG-Signature': 'v1=ac428c7e1a5fba49346b0b0ddee84e49fbdb739eb3e6ecc3890384d428d0855b',
	},
};

// the verification process on your side
const headerSignature = eventReceived.headers['SG-Signature'].split('v1=')[1];
const verifiedSignature = getHmac(JSON.stringify(eventReceived.payload), YOUR_WEBHOOK_SECRET_KEY);

const test = headerSignature === verifiedSignature;
console.log('signature match', test); // = true

<?php

// your platform webhook secret key
$YOUR_WEBHOOK_SECRET_KEY = 'thisisasecret';

// Extract data from our POST request :
// 1. SG-Signature header (remove 'v1=' from signature)
$signature = substr("v1=ac428c7e1a5fba49346b0b0ddee84e49fbdb739eb3e6ecc3890384d428d0855b", 3);
// 2. raw content (content-type: application/json)
$payload = '{"event":"order.completed","id":"ord_seed1","date":1567430953297}';

// get hmac from payload
$hmac = hash_hmac('sha256', $payload, $YOUR_WEBHOOK_SECRET_KEY);

// compare with signature
var_dump(hash_equals($hmac, $signature)); // = true

Retry mechanism

When we sends a notification to the notifyUrl but do not receive a 2XX response from it, a retry mechanism begins. We automatically resend our notification every 3 minutes up to 5 times.

Attention

Requests sent to the notifyUrl will time out after 30 seconds. Therefore it's important for your endpoint to return a 2xx response before this time expires (e.g asynchronous processing). Otherwise, the notification will be retried and you will receive the request again, even though your processed it successfuly after 30 seconds the first time.

Precision

Although this is a rare occurrence, we recommend that you process webhooks notifications in a manner that anticipates duplicates events, and only treat them according to your logic. For example, you could check the webhooks received and ignore it if you already treated it, by looking at its unique identifier eventId as an idempotency key.

List of events

Below the list of events sent by ShareGroop to your endpoint, depending on the workflow set up for your integration.

Precision

For enhanced security reason, we do not send data through our notifications, only events. So you may then need to retrieve data according to our API References upon notifications.

Resource: Order

{
    eventId: 'event_id',
    event: 'event_name', // the event, listed below
    date: 1567430953297, // date of event, timestamp epoch millisecond
    id: 'ord_...', // the order.id
    orderId: 'ord_...', // the order.id
}

Event	Description	Trigger
order.confirmed	Sent when an order is confirmed.	An order is confirmed when the first transaction authorization has been made. You should get this notification instantly after the customer paid in the widget.
order.completed	Sent when an order is completed.	An order is completed when the total amount collected equals to the requested order amount.
order.canceled	Sent when an order is canceled.	After cancelling an Order, from API or Dashboard : All : An order is canceled when merchant cancel it via API or Dashboard. Split - Standard mode: An order is canceled when the due date has been reached while the total amount confirmed by captain and cobuyers didn't reach order amount.
order.refunded	Sent when an order is refunded.	After requesting an Order refund, from API or Dashboard : All : An order is refunded when all captured tranaction are fully refunded. (The total amount of refunded transactions equals the total amount captured on the Order.) Installment: An order is refunded when all transactions are fully refunded or voided.
order.pendingCommit	Sent when an order is pendingCommit.	Only for two-phase commit integration
order.pending	Sent when an order is pending.	If an order is waiting to receive a bank transfer (virtual IBAN payment method).
order.notPending	Sent when an order is notPending.	If an order has received a bank transfer while it was not awaiting one.
order.support	Sent when an order is support.	If something with the order requires manual support action.

Resource: Transaction

{
    eventId: 'event_id',
    event: 'event_name', // the event, listed below
    date: 1567430953297, // date of event, timestamp epoch millisecond
    id: 'auth_...', // the transaction.id
    orderId: 'ord_...', // the order.id
    transactionId: 'auth_...', // the transaction.id
}

Event	Description	Trigger
transaction.authorized	Sent when a transaction is authorized.	A transaction is authorized when an authorization request succeeded.
transaction.captured	Sent when a transaction is captured.	A transaction is captured when a capture request on an authorized transaction succeeded.
transaction.failed	Sent when a transaction is failed.	A transaction is failed when an action on a transaction has failed. Failure code and reason can be found in the transaction detail.
transaction.refunded	Sent when a transaction is refunded.	A transaction is refunded when the last requested refund succeeded, and nothing remains to refund.
transaction.refundedPartial	Sent when a transaction is refundedPartial.	A transaction is partially refunded when the last requested refund succeeded, but part of the captured amount can still be refund
transaction.refundFailed	Sent when a transaction is refundFailed.	A transaction is refundFailed when the refund has failed. Failure code and reason can be found in the transaction detail.
transaction.voided	Sent when a transaction is voided.	A transaction is voided when a void request succeeded.
transaction.voidFailed	Sent when a transaction is voidFailed.	A transaction is voidFailed when the transaction void has failed. Failure code and reason can be found in the transaction detail.
transaction.chargeback	Sent when a chargeback has been emitted by the bank for a given transaction.	This event is emitted when we are notified that a user has contested a payment made his card to his bank. In this context, you should contact your user to clarify the situation. The transaction's status does not change in this case and stays to its latest state.

Resource: Installment

{
    eventId: 'event_id',
    event: 'event_name', // the event, listed below
    date: 1567430953297, // date of event, timestamp epoch millisecond
    id: 'inst_...',  // the matching order.installments[].id
    orderId: 'ord_...', // the order.id
    transactionId: 'auth_...', // the transaction.id
    installmentId: 'inst_...' // the matching order.installments[].id
}

Event	Description	Trigger
installment.paid	Sent when an order's installment is paid.	The pending (or unpaid) transaction linked to the installment has been paid (authorized), and the corresponding order.installments[] becomes `paid`.
installment.unpaid	Sent when an order's installment is unpaid.	The scheduled payment of the pending (or unpaid) transaction linked to the installment has failed (transaction.status: `failed`). The corresponding order.installments[] becomes `unpaid`.
installment.recoveryFailed	Sent when an order's installment is still unpaid after all recovery attempts.	Recovery can be configured on your module to retry failed automatic payments X times for a maximum of X attempts. When the installment is still unpaid after all attempts, you can act on it.

Resource: Invoice

{
    eventId: 'event_id',
    event: 'event_name', // the event, listed below
    date: 1567430953297, // date of event, timestamp epoch millisecond
    id: 'inv_...',  // the invoice.id
    invoiceId: 'inv_...' // the invoice.id
    orderId: 'ord_...', // the last order.id attached to this invoice
}

Event	Description	Trigger
invoice.paid	Sent when an invoice is paid.	An invoice is `paid` when an attached order is completed
invoice.unpaid	Sent when an invoice is unpaid.	An invoice is `unpaid` when the invoice dueDate is reached, or every time an automatic payment attempt fails on the invoice.
invoice.recoveryFailed	Sent when an invoice is still unpaid after all recovery attempts.	Recovery can be configured on your module to retry failed automatic payments X times for a maximum of X attempts. When the invoice is still unpaid after all attempts, you can act on it.

Resource: Subscription

{
    eventId: 'event_id',
    event: 'event_name', // the event, listed below
    date: 1567430953297, // date of event, timestamp epoch millisecond
    id: 'inv_...',  // the subscription.id
    subscriptionId: 'sub_...', // the subscription id,
    lastInvoiceId: 'inv_...', // the last invoice id
    orderId: 'ord_...', // the latest order.id attached to the last invoice of this subscription
}

Event	Description	Trigger
subscription.active	Sent when a Subscription becomes active.	A Subscription becomes `active` after the first payment (`initiated` -> `active`), sating it has been But also after a successful recovery (`unpaid` -> `active`)
subscription.unpaid	Sent when an invoice is unpaid.	A Subscription becomes `unpaid` when the latest subscription invoice becomes unpaid.
subscription.ended	Sent when a Subscription reached its end date.	A Subscription becomes `ended` when current date reached specified subscription `endAt` date.

Note

If your ShareGroop platform has been created before 2020-06-30, and you are updating your ShareGroop webhooks integration, you should contact support@sharegroop.com or your designated ShareGroop Success Manager, to review your webhooks configuration.