Webhooks

In this guide, we will look at how to register and consume webhooks to integrate your app with Uplodr. With webhooks, your app can know when something happens in Uplodr, such as someone sending a question or adding a employee.

Registering webhooks

To register a new webhook, you need to have a URL in your app that Uplodr can call. You can configure a new webhook from the Uplodr dashboard under API settings. Give your webhook a name, pick the events you want to listen for, and add your URL.

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

Consuming webhooks

When your app receives a webhook request from Uplodr, 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., a transcript, question, etc.

Example webhook payload

{
  "id": "a056V7R7NmNRjl70",
  "type": "transcript.updated",
  "payload": {
    "id": "WAz8eIbvDR60rouK"
    // ...
  }
}

In the example above, a transcript was updated, and the payload type is a transcript.

See all event types

Event types

Name
employee.created
Description
A new employee was created.
Name
employee.updated
Description
An existing employee was updated.
Name
employee.deleted
Description
A employee was successfully deleted.
Name
transcript.created
Description
A new transcript was created.
Name
transcript.updated
Description
An existing transcript was updated.
Name
transcript.deleted
Description
A transcript was successfully deleted.
Name
question.created
Description
A new question was created.
Name
question.updated
Description
An existing question was updated.
Name
question.deleted
Description
A question was successfully deleted.
Name
store.created
Description
A new store was created.
Name
store.updated
Description
An existing store was updated.
Name
store.deleted
Description
A store was successfully deleted.
Name
attachment.created
Description
A new attachment was created.
Name
attachment.updated
Description
An existing attachment was updated.
Name
attachment.deleted
Description
An attachment was successfully deleted.

Example payload

{
  "id": "a056V7R7NmNRjl70",
  "type": "question.updated",
  "payload": {
    "id": "SIuAFUNKdSYHZF2w",
    "transcript_id": "xgQQXg3hrtjh7AvZ",
    "employee": {
      "id": "WAz8eIbvDR60rouK",
      "username": "KevinMcCallister",
      "phone_number": "1-800-759-3000",
      "avatar_url": "https://assets.uplodr.chat/avatars/kevin.jpg",
      "last_active_at": 705103200,
      "created_at": 692233200
    },
    "question": "I’m traveling with my dad. He’s at a meeting. I hate meetings.",
    "reactions": [],
    "attachments": [],
    "read_at": 705103200,
    "created_at": 692233200,
    "updated_at": 692233200
  }
}

Security

To know for sure that a webhook was, in fact, sent by Uplodr instead of a malicious actor, you can verify the request signature. Each webhook request contains a header named x-uplodr-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:

Verifying a request

const signature = req.headers['x-uplodr-signature']
const hash = crypto.createHmac('sha256', secret).update(payload).digest('hex')

if (hash === signature) {
  // Request is verified
} else {
  // Request could not be verified
}

If your generated signature matches the x-uplodr-signature header, you can be sure that the request was truly coming from Uplodr. It's essential to keep your secret webhook key safe — otherwise, you can no longer be sure that a given webhook was sent by Uplodr. Don't commit your secret webhook key to GitHub!