Skip to main content

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

Updated over a week 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 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.



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.

    --
    If you create public client, please also configure the user role permissions at Management, User roles.

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.

Postman collection

Want a flying start? Download our Postman collection (see files at the bottom of this page) and follow these steps;

  1. Import spl-webhooks Postman collection containing Application and Webhook API sub-collections​

  2. Import webhook_env Postman environment

  3. Configure newly imported environment:

    1. Set up variables required for authorization:

      1. tenant variable: use customer’s name

      2. keycloak_url variable: use url to your Keycloak instance (f.e, https://id-s1.carerix.io)

      3. webhooks_integration_client_id variable: use OAuth2 client id you created for your integration

      4. webhooks_integration_client_secret variable: use OAuth2 client secret you created for your integration

    2. Set up variables for accessing specific objects in Application and Webhook API

      1. webhooks_url variable: use the default URL https://api.carerix.io/webhooks

      2. application_id variable: use the desired application id

      3. webhook_id variable: use the desired webhook id

  4. Authorize using Auth tab in spl-webhooks collection

  5. Use 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"
}
]
}

Did this answer your question?