Webhooks provide a powerful way to get real-time updates from your Awardco platform, enabling seamless integration with your other applications. Unlike traditional APIs that require you to constantly check for new information, webhooks automatically send data to your specified location as soon as a relevant event occurs in Awardco. This ensures you always have the most up-to-date information, without any delays.
Currently, our webhooks feature focuses on Recognition events, meaning you can instantly receive data about recognitions as they happen in Awardco. This data includes details like the giver, recipient, point amount, recognition note, and the program name. This article will walk you through how to create, configure, and manage webhooks to sync recognition data from your Awardco platform to your chosen endpoint.
Webhook Use Case
Webhooks allow your organization to display real-time recognition updates on off-platform social feeds, such as a company intranet.
Unlike connecting with feed API calls, the process is instant with webhooks. As soon as a recognition is submitted in your Awardco platform, the webhook is triggered, and the recognition data is immediately sent to your specified endpoint, allowing for instant updates on your external feeds.
Navigating to the Webhook Creator
To begin creating and managing webhooks:
- Log into your recognition platform.
- On the homepage, select the Admin button at the bottom of the left navigation menu.
- Select “Platform”, then “Integrations, then “Webhooks” from the left navigation menu.
On the Webhooks page, you'll see a list of any existing webhooks. To create a new one, click the Create Webhook button.
Creating a Webhook
When you click "Create Webhook," a modal will appear where you can configure your new webhook. Here's a breakdown of each field:
- Name: Give your webhook a descriptive name. This will help you identify it later, especially if you have multiple webhooks.
- Trigger Events: This dropdown currently has one option: Recognition Complete. This means your webhook will activate whenever a recognition is successfully sent in Awardco. We are open to adding more trigger event types in the future based on client requests.
- Endpoint URL: This is the URL where the recognition data will be sent. You are responsible for providing this URL. This is the "location" your webhook will communicate with.
- Secret Key: This is an auto-generated security measure. When a webhook request is sent from Awardco, you will use this secret key to create a signature. This signature is then compared to a signature Awardco sends. If they match, it verifies that the data is genuinely coming from Awardco and not a malicious third party. For more technical details on how to generate this signature, refer to the "Webhook Verification" section in our API documentation.
- Error Recipient Emails: If there are any issues with your webhook delivering data, error logs will be sent to the email addresses listed here. You can add multiple email addresses by separating them with commas.
- Status: Toggle this to Active for event data to be delivered when the trigger event occurs. Setting it to Inactive will pause the webhook.
- Run Test: Click this button to send dummy recognition data to your specified Endpoint URL. This allows you to verify that your webhook is set up correctly before it goes live with real data. Remember to delete any test recognitions that appear on your off-platform feed after running a test.
Managing Webhooks
Once you've created a webhook, you can manage it from the main Webhooks page. Next to each webhook, you'll find a three-dot menu with the following options:
- View Details: This option displays general information about the webhook, including the ability to copy the secret key.
- Edit: This brings you back to the webhook creation modal, where you can modify any of the webhook's settings.
- Run Test: Similar to the "Run Test" button during creation, this sends dummy data to your Endpoint URL to ensure the webhook is functioning as expected.
- Set Inactive: This pauses the webhook, preventing it from being triggered and sending data.
- Set Active: (Only visible if the webhook is inactive) This reactivates the webhook, allowing it to be triggered again.
- Delete: This permanently removes the webhook.
FAQ
-
Q: What's the difference between webhooks and APIs?
- A: APIs typically require you to make requests to pull data. Webhooks, on the other hand, are "event-driven," meaning they automatically push data to your specified endpoint as soon as a particular event (like a recognition being sent) occurs. This makes webhooks ideal for real-time updates.
-
Q: Can I get webhooks for events other than "Recognition Complete"?
- A: Currently, "Recognition Complete" is the only available trigger event. We are exploring adding more trigger event types in the future. If you have a specific use case, please reach out to your Awardco point of contact.
-
Q: Where can I find more technical documentation on webhooks?
- A: Our API documentation includes a dedicated section on webhooks, which provides more technical details, including information on how to generate a signature from your secret key for webhook verification. While in beta, this page can be accessed directly at: https://api.awardco.com/api/webhooks
If you have any questions, please contact Awardco Admin Support.