Skip to main content
All CollectionsFeatures
Creating your first webhook: a step-by-step guide with popular examples
Creating your first webhook: a step-by-step guide with popular examples
Updated over 2 months ago

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.



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)

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 Q4). 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"
}
]
}

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

Did this answer your question?