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 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.
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.
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"
}
]
}
Please note that our service does not yet validate your request (on our roadmap, expected in Q3). Therefore, we currently will not notify if your webhook is incorrect.
Ensure your requests are correct and free of typos or double spaces!
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
POST https://api.carerix.io/webhooks/v1/applications/{webhook_application_id}/webhooks
{
"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"
}
]
}