Webhooks

You can use Ucentric's webhook feature to subscribe, in real time, to events related to your user's Ucentric activity. Webhooks can only be used on a payment plan that supports webhooks. 

Creating A Webhook

To create a new webhook, visit the integrations page. You may only have one webhook destination per Ucentric account.

Next, enter the URL you want webhook events sent to. Note this URL must:

  • Be able to receive POST requests in JSON format
  • Must return a 200 level status in the response

You may optionally add a header key/value pair to each request.

Lastly, click the "Create Webhook" button.

You will see a message confirming the webhook has been created. Next you can copy the signing key to verify requests. If you are ready to start receiving events, check "Enabled?" and click "Update Webhook".

Subscribing To Events

After creating a new webhook, to subscribe to events, navigate to the "Subscriptions" tab. There you will see a list of all the events you can subscribe to. Check off the events you'd like to be notified of, and then click "Update Subscriptions".

Removing A Webhook

To remove a webhook, navigate to the "Setup" tab and click the trash icon in the bottom right.

After confirming you'd like to delete this webhook, the webhook will be removed.

Verifying Webhook Signatures

Every webhook you create also creates a unique and secret signing key. Ucentric uses this key to sign the webhook's body. This signature can be found in the HTTP request's x-ucentric-signature header. You can use this key in your application to verify that the webhook you are receiving was actually sent by Ucentric.

On the webhook's setup tab, start by revealing and copying your signing key:

Next, in your application code, hash the webhook body, creating an HMAC with your signing key. The following is an example implementation written in Node.js code using the Express framework. 

app.post('/webhook', async (req, res) => {
  const header = req.headers['x-ucentric-signature'];
  const hmac = crypto.createHmac('sha256', WEBHOOK_SECRET);
  hmac.update(req.rawBody);
  const hash = hmac.digest('hex');

  if (header !== hash) {
    throw new Error('Invalid Webhook Signature');
  }

  res.send('OK');
});

Webhook JSON Structure

Every webhook will be formatted in JSON, using the format below:

{
  "userId": "userid_you_set",
  "event": "Ucentric Clicked Notification",
  "type": "track",
  "timestamp": "2006-01-02T15:04:05Z0700",
  "properties": {
    NotificationId: "32442343-234234-234343"
  }
}

Field Definitions:

Field Name Data Type Description
userId string user's ID
event string subscribed event
type string type of event, usually "track"
timestamp string ISO-8601 formatted date string
properties object<string:string|number> event contextual information

Still need help? Contact Us Contact Us