Welcome to our guide on creating your first webhook!
In this article, we will guide you through the process step-by-step and provide you with popular examples and a Postman collection to help you get started.
Once your webhook is configured, Carerix will send POST requests to the specified URL whenever one of the selected events occurs.
Also see: Introducing Webhooks
Let's try to create and test your first webhook!
To get started, here's what you'll need:
Carerix System with Webhooks Feature Activated
Carerix System with Webhooks Feature Activated
Example: yourcompany.carerix.net
OpenID client
OpenID client
Confidential OAuth2 Client
Code in format 'urn:{vendor}/{application name}
The token must have the
urn:cx/webhooks:data:manage
scope.For more information - IAM documentation
Add Permission Matrix
Dont forget to a Add the Permission matrix.
--
If you create public client, please also configure the user role permissions at Management, User roles.
Endpoint for receiving notification (webhook events)
Endpoint for receiving notification (webhook events)
This could be your own service, or you can use a service like webhook.site or hookdeck
Steps to create and receive your first webhooks
Step 1: Create a Webhook Application
Step 1: Create a Webhook Application
1.1. Authenticate, via an API platform like Postman and user your created Client ID & Client secret.
Note: the Access Token url can vary.
https://id.carerix.io/auth/realms/csmdemo/protocol/openid-connect/token
https://id-2.carerix.io/auth/realms/csmdemo/protocol/openid-connect/token
https://id-3.carerix.io/auth/realms/csmdemo/protocol/openid-connect/token
https://id-4.carerix.io/auth/realms/csmdemo/protocol/openid-connect/token
etc
Go to your application url, like automations.carerix.net and check the url.
https://id-s1.carerix.io/auth/realms/automations/protocol/....
1.2 Create a Webhook Application
Make a POST request to the Webhooks Management API: https://api.carerix.io/webhooks/v1/applications/
Request body:
{ "_kind": "Application", "name": "my-first-application" }
Expected response
{ "_kind": "Application",
"_id": "192e953d-1e3a-4513-b14c-a66bca4be005"
}Note: you need to use the
applicationId
that you receive from the response. 192e953d-1e3a-4513-b14c-a66bca4be005 is an example.
Step 2: Create a Webhook under the Application
Step 2: Create a Webhook under the Application
Create a Webhook
Important: replace the placeholders:
{{applicationId}} with your Webhook Application ID from Step 1.
{{your_endpoint_url}} with the URL of your endpoint that will receive the webhook events.
Make a POST request to the Webhooks Management API: https://api.carerix.io/webhooks/v1/applications/${{applicationId}}/webhooks
example1 ; Request body:
{
"url": "http://example.url",
"_kind": "Webhook",
"filters": [
{
"eventType": "cremployee:updated",
"condition": "data.tostatusnode eq '1234' "
}
]
}
example 2 ; Request body:
{
"url": "http://example.url",
"_kind": "Webhook",
"filters": [
{
"eventType": "crjob:created",
}
]
}
Step 3: Trigger the Webhook
Step 3: Trigger the Webhook
Go to the Carerix Application
Change any field of a Candidate.
Step 4: Verify the Webhook Event
Step 4: Verify the Webhook Event
Check Your Receiving Endpoint
Ensure your endpoint receives the webhook request.
Expected payload:
{
"id": "8469bf71-4942-45ea-98b8-393077288785",
"time": "2024-02-14T14:24:40Z",
"type": "cremployee:updated",
"applicationId": "192e953d-1e3a-4513-b14c-a66bca4be005", "webhookId": "4c3174c9-deab-426a-8d26-23bbc89e461e",
"tenant": "cxdev50streamer",
"data": { "entityId": "1",
"changedFields": [ "touser.attributechanges", "touser", "touser.lastname", "modificationdate", "touser.modificationdate" ] } }
By following these steps, you will successfully create and test a webhook in the Carerix system.
Postman collection
Want a flying start? Download our Postman collection (see files at the bottom of this page) and follow these steps;
Import
spl-webhooks
Postman collection containing Application and Webhook API sub-collectionsImport
webhook_env
Postman environmentConfigure newly imported environment:
Set up variables required for authorization:
tenant
variable: use customer’s namekeycloak_url
variable: use url to your Keycloak instance (f.e, https://id-s1.carerix.io)webhooks_integration_client_id
variable: use OAuth2 client id you created for your integrationwebhooks_integration_client_secret
variable: use OAuth2 client secret you created for your integration
Set up variables for accessing specific objects in Application and Webhook API
webhooks_url
variable: use the default URL https://api.carerix.io/webhooksapplication_id
variable: use the desired application idwebhook_id
variable: use the desired webhook id
Authorize using
Auth
tab inspl-webhooks
collectionUse the issued access token to access Application and Webhook API
Frequently used conditions
Popular examples
Example 1: Placement status is set to "Active" or "Closed"
POST - https://api.carerix.io/webhooks/v1/applications/{webhook_application_id}/webhooks
{
"url": "https://yourwebhookurl.net/12345",
"_kind": "Webhook",
"filters": [
{
"eventType": "crjob:updated",
"condition": "data.tostatusnode eq '1234' or data.tostatusnode eq '5678'"
}
],
"customHeaders": [
{
"name": "Custom-Signature",
"value": "FE: Basic Y3g1YXBpY2xpZW50OmN4NWNvbm5lY3RhcGlmZWF0dXJl"
}
]
}
Example 2: Candidate status is set to "Open for work"
{
"url": "https://yourwebhookurl.test",
"_kind": "Webhook",
"filters": [
{
"eventType": "cremployee:updated",
"condition": "data.touser.tosinglestatusnode eq '1234'"
}
],
"customHeaders": [
{
"name": "Custom-Signature",
"value": "FE: Basic Y3g1YXBpY2xpZW50OmN4NWNvbm5lY3RhcGlmZWF0dXJl"
}
]
}
Example 3: Match is updated
Important: We strongly advise always using conditions in your webhooks to reduce unnecessary notifications (noise) and ensure only relevant updates trigger a webhook.
{
"url": https://yourwebhookurl.test",
"_kind": "Webhook",
"filters": [
{
"eventType": "crmatch:updated"
}
],
"customHeaders": [
{
"name": "Custom-Signature",
"value": "FE: Basic Y3g1YXBpY2xpZW50OmN4NWNvbm5lY3RhcGlmZWF0dXJl"
}
]
Example 4: Matchstage is updated to stage "Intake"
POST
{
"url": https://yourwebhookurl.test",
"_kind": "Webhook",
"filters": [
{
"eventType": "crmatch:updated",
"condition": "data.statusinfo eq '1234'"
}
]
}
Example 5: New Match is created
POST
{
"url": https://yourwebhookurl.test",
"_kind": "Webhook",
"filters": [
{
"eventType": "crmatch:created"
}
]
}
Example 6: New Publication is created
POST
{
"url": https://yourwebhookurl.test",
"_kind": "Webhook",
"filters": [
{
"eventType": "crpublication:created"
}
]
}
Example 7: Candidate firstname / lastname is Updated
POST
{
"url": "https://yourwebhookurl.test",
"_kind": "Webhook",
"filters": [
{
"eventType": "cremployee:updated",
"condition": "metadata.paths has any of ['toUser.firstName','toUser.lastName']"
}
],
"customHeaders": [
{
"name": "Custom-Signature",
"value": "FE: Basic Y3g1YXBpY2xpZW50OmN4NWNvbm5lY3RhcGlmZWF0dXJl"
}
]
}