Setting up webhooks to trigger event notifications
Replicon offers a webhooks API you can use to set up event-driven notifications in Replicon or Polaris.
To use our webhooks, you’ll need to set up a subscription for each event you want to track using GraphQL. Then, when an event occurs, a call including basic details of that event will be posted at your designated, public-facing target URL. For example, for a user modified event, the call’s payload will show which user was modified, but not the change that was made.
Webhooks notifications have many potential uses, especially in providing automated notification, and in integrations with third-party apps. They provide an advantage over polling-based integrations, as they can help you isolate items involved in an event, that you can then use in more targeted operations.
Webhooks usage examples
Below are some examples of scenarios where webhooks could be useful.
In most of these scenarios, the webhook is used to identify items involved in a change event, so you can carry out further processing or analysis of those items using Replicon or Polaris’ full API.
|
ProjectTeamModified |
By combining this webhook with a Replicon service, you can track team changes, and update assignment details in your downstream system so it stays in sync with Replicon. You can also build a custom notification to automatically update specific administrators or other stakeholders when changes are made. |
|
ProjectStatusChanged |
You could set up a custom notification that’s sent to project managers or other team members when projects are closed. Plus, you could use this webhook to update project statuses in downstream apps. |
|
TimeOffStatusChangedToRejected |
You can set up auto-deletion of rejected bookings, so they don’t impact payroll. Or, you could create a custom notification that’s triggered when bookings are rejected, so administrators and supervisors can delete them. |
|
TimesheetDeleted |
You could set up a notification altering managers when timesheets are deleted. |
Our custom development team may be able to create custom applications to meet your requirements. Contact your Customer Success manager or Replicon Support for more information.
Webhooks supported events
There are many possible uses for setting up a webhooks subscription. These are the events we currently support:
|
|
You can also find this list in the API schema.
Webhooks permissions and security
Webhooks have tenant-wide access, meaning they can access all of your Replicon or Polaris data. And, you can’t limit subscriptions to target particular permissions or access levels.
Administrators must be assigned the Integration Settings permission to use webhooks, so you can limit access to only those who need it.
You can track the authenticity of each webhooks call using the secret key generated when you create a subscription. See below for more information.
Working with webhooks
Accessing the webhooks API
Webhooks subscriptions are set up and managed using Replicon or Polaris’s GraphQL Playground.
If you’re not familiar with GraphQL, you can learn more about it on the GraphQL site.
To access the GraphQL Playground:
- Log in to your Replicon or Polaris instance as an administrator.
By logging in, you'll be automatically authenticated when you launch the Playground.
- Ensure you have Integration Settings permission.
- Access the Playground at https://<Your swimlane>.replicon.com/webhook-api/graphql.
Replace <Your swimlane> with the swimlane code found in your instance’s URL.
Your swimlane (or endpoint) is the environment where your instance is hosted, and uses the format na7, sb1, eu1, etc. So, the URL might look like this: https://na7.replicon.com/webhook-api/graphql.
You can view the webhooks API documentation and schema, which list the available API operations, from within the GraphQL Playground environment.
Adding a webhook subscription
Refer to Webhooks supported events above for a list of the currently-supported events.
To set up a webhook subscription:
- Access the GraphQL Playground while logged in to your instance, as described in Accessing the webhooks API.
- Enter the code given below.
In the targetUrl parameter, include the public URL you want called when the event occurs. You can use a website like webhook.site to access a temporary public URL where you can test your webhook.
You can update the name of the mutation given in the first line, and the eventType parameter.
|
mutation CreateTimesheetWaitingWebhook { createWebhookSubscription (input: { eventType: TimesheetStatusChangedToWaiting targetUrl: "https://mytargeturl.site" }) { subscription { id sharedSecret } } } |
Click the play button. You should see a “data” response if the call was successful:
|
{"data": { "createWebhookSubscription": { "subscription": { "id": "urn:replicon-tenant:0c1f0bdc9d434b70833a891dc3721ee8:webhook-subscription:16f244f2-10bf-4ed4-bb3b-6e1f362dc357", "sharedSecret": "c314cbd7-63e2-4c5b-aad1-06135e2b8f4e" } } } } |
Your subscription is now live.
You can test the subscription by carrying out the event.
For example, if you’ve subscribed to the TimesheetStatusChangedToWaiting event, submit a timesheet (one with approvers assigned).
If you’re using webhook.site, you should see a post for the call appear in the left panel, and you’ll see details of the event (the event payload) under Raw Content.
The shared secret, used to authenticate event-triggered calls, is only shown when you create a subscription, and cannot be retrieved later. Therefore, save it somewhere.
Using the secret key to confirm authenticity of a post
You can authenticate that the payload you received originated from Replicon and that it wasn’t tampered with by using the secret key that was generated when you created the subscription.
To authenticate manually:
- Access a hash-based message authentication code (HMAC) generator.
- Copy the full payload, and paste it into the generator’s string field.
- Find the secret key that was generated when you created the subscription, and paste it into the Secret Key field of the generator.
- Click Compute.
A computed string should display. If the payload is authentic, this output string should match the x-replicon-webhook-signature header from the call.
Updating a webhook subscription
You can change the target URL and event type for any existing subscription. This is most commonly used to correct errors in the subscription.
Use the following code to update a subscription, replacing the examples with the applicable subscription ID, event type, and target URL:
|
mutation { updateWebhookSubscription (input: { id: "urn:replicon-tenant:0c1f0bdc9d434b70833a891dc3721ee8:webhook-subscription:7e12ad50-880a-464f-89b7-8a1d913ee471" eventType: TimesheetStatusChangedToWaiting targetUrl: "https://mytargeturl.site" }) { subscription { id } } } |
Deleting a webhook subscription
Once you no longer need a subscription, you can delete it using this code, updated with the applicable subscription ID:
|
mutation { deleteWebhookSubscription (input: { id: "urn:replicon-tenant:0c1f0bdc9d434b70833a891dc3721ee8:webhook-subscription:140f4d16-cbcb-47e2-8104-1624c3d040f7" }){ id } } |
Checking which subscriptions are active
Once you’ve set up one or more subscriptions, you might need to check which ones are currently active for your tenant. To do that, use the following code:
|
{ webhookSubscriptions { items { id eventType } } } |
Several other item parameters are available on the webhookSubscriptions query, such as targetUrl, createdTimestamp, and updatedTimestamp. You can find a full list in the webhooks documentation, under webhookSubscriptions.
Troubleshooting failed subscriptions
Sometimes, the call fails to be delivered. This might occur, for example, if your target URL is down for some reason.
Our webhooks are configured to retry 10 times, at exponential intervals.
You can debug why delivery might have failed using the webSubscription query. As shown below, you can include parameters for the event and for attempts made to send the call.
|
{ webhookSubscription(id: "urn:replicon-tenant:0c1f0bdc9d434b70833a891dc3721ee8:webhook-subscription:140f4d16-cbcb-47e2-8104-1624c3d040f7") { id webhookEvents { items { id state jsonPayload webhookAttempts { items { id status timestamp durationInMilliseconds response } } } } } } |
If you think the cause of the issue has been fixed, you can immediately retry sending the call using the retryWebhookEvent mutation, substituting the applicable event ID and subscription ID:
|
mutation { retryWebhookEvent(input: { id: "urn:replicon-tenant:0c1f0bdc9d434b70833a891dc3721ee8:webhook-event:e337cb88-ef39-4b46-a9ae-31714e237f60" subscriptionId: "urn:replicon-tenant:0c1f0bdc9d434b70833a891dc3721ee8:webhook-subscription:5ea01577-3038-4415-aa5e-aa00ae9d2fc0" }) { webhookEvent { id state } } } |
FAQs
Is there a single event ID per subscription?
No. Each subscription has its own unique ID, and each event that occurs for that subscription has a unique ID.
Can we track events across multiple tenants with one subscription?
No. The webhooks API is tenant-scoped, meaning subscriptions apply to a single Replicon or Polaris tenant only.
Can we track calls using correlation IDs?
Yes, a correlation ID for each call is available in its header.
Can you add a particular new event for us?
We are continuing to add support for additional events. If you have a request, contact Replicon Support, and we’ll consider it.
Could you include more details in the payload?
Technical constraints limit what we can include in the payload for a call, so we’re not likely to expand the details included. However, you can combine webhooks notifications with requests made via our other API offerings to gather more data.
Will calls occur in the order that events occurred?
No, we don’t guarantee the order of delivery.
Related links
Introduction to the Replicon API
Using BYOK encryption with Replicon
Rate limiting
Viewing the available API operations
