Creating your first webhook: a step-by-step guide with popular examples

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

Example: yourcompany.carerix.net

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)

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

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

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

Go to the Carerix Application

Change any field of a Candidate.

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"

POST - https://api.carerix.io/webhooks/v1/applications/{webhook_application_id}/webhooks

{
    "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

https://api.carerix.io/webhooks/v1/applications/{webhook_application_id}/webhooks

{
"url": https://yourwebhookurl.test",
    "_kind": "Webhook",
    "filters": [
        {
            "eventType": "crmatch:updated",
              "condition": "data.statusinfo eq '1234'"
        }
    ]
}

Example 5: New Match is created

POST

https://api.carerix.io/webhooks/v1/applications/{webhook_application_id}/webhooks

{
"url": https://yourwebhookurl.test",
    "_kind": "Webhook",
    "filters": [
        {
            "eventType": "crmatch:created"
        }
    ]
}

Example 6: New Publication is created

POST

https://api.carerix.io/webhooks/v1/applications/{webhook_application_id}/webhooks

{
    "url": https://yourwebhookurl.test",
    "_kind": "Webhook",
    "filters": [
        {
            "eventType": "crpublication:created"
        }
    ]
}

Introducing Webhooks in Carerix