Webhooks

In this guide, we will look at how to register and consume webhooks to integrate your app with Vincy. With webhooks, your app can know when something happens in Vincy, such as someone clicking your shortlink.

Registering webhooks

To register a new webhook, you need to have a URL in your app that Vincy can call. You can configure a new webhook from the Vincy dashboard under Developers. Be sure to give a valid https URL. For local development, you can use ngrok to expose your local server to the internet.

Now, whenever something of interest happens, a webhook is fired off by Vincy. In the next section, we'll look at how to consume webhooks.

Consuming webhooks

When your app receives a webhook request from Vincy, check the type attribute to see what event caused it. The first part of the event type will tell you the payload type, e.g., an engagement.

{
  "id": "eng_02xiz5Am1QUnEdCXeUiykl",
  "type": "engagement.shortlink.clicked"
  "occurred_at": "2024-09-18T17:32:25Z",
  "data": {
    "city": null,
    "country": null,
    "shortlink": {
      "code": "deadlock-tips",
      "id": "sl_7Oz4SiCxGQvfJAGPWRJtTM",
      "url": "https://www.youtube.com/watch?v=9v3ZXJA5jVM"
    },
    "type": "click",
    "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/128.0.0.0 Safari/537.36"
  }
}
                    

In the example above, a shortlink was clicked, and the payload type is an engagement.

Event types

Security

To know for sure that a webhook was, in fact, sent by Vincy instead of a malicious actor, you can verify the request signature. Each webhook request contains a header named Vincy-Signature, and you can verify this signature by using your secret webhook key. The signature is an HMAC hash of the request payload hashed using your secret key. Here is an example of how to verify the signature in your app:

const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const computedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  
  return crypto.timingSafeEqual(
    Buffer.from(computedSignature, 'hex'),
    Buffer.from(signature, 'hex')
  );
}
                        

Compare your generated signature with the one provided in the Vincy-Signature header, you can be sure that the request was truly coming from Vincy. It's essential to keep your secret webhook key safe — otherwise, you can no longer be sure that a given webhook was sent by Vincy. Don't commit your secret webhook key to Github!