Webhooks

Govalo now offers Webhooks, extending customization capabilities for your digital gifting experience.

In this article

• Webhooks explained
• Security
• Govalo Webhooks
  • Gift Cards
• Gift card created
• Gift card redeemed
• Gift card disabled
• Store Credit
  • Store credit created
• Store credit redeemed

Webhooks explained

Webhooks are a mechanism for sending real-time data from one application to another using HTTP requests. They allow developers to build customized integrations between different applications to automate workflows and improve efficiency.

Webhooks work by sending HTTP POST requests to a specified endpoint URL whenever a particular event occurs in Govalo. The receiving application can then use this data to trigger an action or update its own data.

Webhooks are commonly used for a wide range of purposes, including:

• Integration between different applications, such as CRMs and marketing automation platforms
• Notifications for events such as user sign-ups, payment confirmations, and order status updates
• Real-time updates for balances

Security

One important consideration when using webhooks is security. Because webhooks involve sending data between different applications over the internet, it is essential to ensure that the communication is secure and that data is not intercepted or tampered with.

Govalo adds a header (x-govalo-signature-sha-256) to the HTTP POST request that includes a signed HMAC using a secret key. This helps to ensure that the data being sent between applications is not tampered with or sent by unauthorized parties. The secret key is known only to the sending and receiving applications and is used to generate the HMAC, which is then included in the header of the request.

The signature is created with HMAC (Hash-based Message Authentication Code) using the SHA-256 hashing algorithm and stored as a hexadecimal string. Govalo uses your secret to hash the HTML request body. To ensure the payload is valid, you can use hash the raw body using your secret and compare it to the header value.

The following is a webhook validation example using Javascript:

const bodyParser = require("body-parser");
const crypto = require("crypto");
const express = require("express");

const app = express();

const secret = process.env("GOVALO_SECRET");

app.use(bodyParser.raw({ type: "*/*" }));

app.post("/", (req, res) => {
    // Calculate the signature from the raw request body.
    const calculated = crypto
        .createHmac("sha256", secret)
        .update(req.body)
        .digest("hex");

    // Get the signature from the request headers.
    const expected = req.headers["x-govalo-signature-sha-256"];

    if (calculated !== expected) {
        // Normally, you'd just return a 401 here, but for the sake of this example,
        console.log("Invalid signature");
    }
});

app.listen(3008, () => {
    console.log("server started");
});

Govalo Webhooks

To configure a webhook, enter the URL and select the event topics that you’d like to receive. The topics available are listed below.

Gift Cards

Gift card created

Triggered when a gift card is ordered from your store or you create a gift card in Govalo.

{
  "topic": "gift_card_created",
  "data": {
    "id": 157,
    "balance": 10,
    "value": 10,
    "currency": "USD",
    "cardNumber": "dgahg9ac78d99fd6",
    "lastCharacters": "9fd6",
    "source": "app",
    "saleType": "gift_card",
    "deliveryDate": "2023-04-07",
    "toName": "Jane Doe",
    "toEmail": "jane@example..com",
    "fromName": "Ted",
    "fromEmail": "ted@example.com",
    "note": "Happy birthday!",
    "pictureUrl": "<url to picture>"
    "shopifyId": 123456789,
    "shopifyOrderId": null,
    "shopifyProductId": 8028431384894,
    "merchantOrderName": null,
    "createdAt": "2023-04-07T10:46:18-04:00"
  }
}

Note: the Shopify order information is optional and may not exist if the card is created directly in Govalo.

Gift card redeemed

Triggered when the customer uses a gift card.

{
  "topic": "gift_card_redeemed",
  "data": {
    "shopifyId": 123456787,
    "orderId": 123434556,
    "redemptionValue": 1,
    "currency": "USD",
    "orderValue": 5,
    "redemptionDate": "2023-04-07T06:00:00.000Z"
  } 
}

Gift card disabled

Triggered when the gift card is disabled in Govalo.

{
  "topic": "gift_card_disabled",
  "data": {
    "id": 156,
    "value": 5,
    "balance": 5,
    "shopifyId": 12345789,
    "cardNumber": "cdd6d3c5faafgbbg",
    "disabledAt": "2023-04-07T14:44:42.251Z"
  } 
}

Store Credit

Store credit created

Triggered when store credit is created in Govalo.

{
  "topic": "store_credit_created",
  "data": {
    "id": 157,
    "balance": 10,
    "value": 10,
    "currency": "USD",
    "cardNumber": "dgahg9ac78d99fd6",
    "lastCharacters": "9fd6",
    "source": "app",
    "saleType": "gift_card",
    "deliveryDate": "2023-04-07",
    "toName": "Jane Doe",
    "toEmail": "jane@example..com",
    "fromName": "Ted",
    "fromEmail": "ted@example.com",
    "note": "Happy birthday!",
    "pictureUrl": "<url to picture>"
    "shopifyId": 123456789,
    "shopifyProductId": 8028431384894,
    "createdAt": "2023-04-07T10:46:18-04:00"
  } 
}

Store credit redeemed

Triggered when the customer uses the store credit.

{
  "topic": "store_credit_redeemed",
  "data": {
    "shopifyId": 123456787,
    "orderId": 123434556,
    "redemptionValue": 1,
    "currency": "USD",
    "orderValue": 5,
    "redemptionDate": "2023-04-07T06:00:00.000Z"
  } 
}