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

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)

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.

Managing Your Webhooks and Applications

While creating your first webhook is a great start, you may need to monitor, modify, or remove your configurations as your integration grows. The Carerix Webhooks API provides dedicated endpoints for these management tasks.

Read Operations: Monitoring Your Integration

You can retrieve information about your setup at any time. To optimize performance and reduce payload size, the Carerix API uses a fields query parameter. This allows you to specify exactly which properties you want to see in the response.

List Applications: Get a paginated list of all applications. Use ?fields=name to see just the labels.
Get Application Details: Retrieve specific details for one application. Use ?fields=name,secret to obtain the security secret required for signature verification.
List Webhooks: View all webhooks under an application. Use ?fields=filters,url to verify your routing logic.
Check Webhook Status: Fetch a single webhook's configuration. Use ?fields=status,url to confirm if it is currently active.

Example: Read Webhook Response

{"_id":"1234567",
"_kind":"Webhook",
"applicationId":"1234567",
"status":"enabled",
"url":"https://your-endpoint.com/webhooks",
"filters":[{"eventType":"CRCompany:updated",
"condition":"data.name eq 'Company 1'"}]}

Why "Update" is Disabled

To ensure maximum reliability and data consistency, the Carerix Webhooks API does not support direct update operations for existing webhooks or applications.

Consistency: Webhooks use a queuing system. An update could cause a "version mismatch" where events already filtered and queued are delivered under a new, incompatible configuration.
Security: Application configurations affect delivery security features. Handling multiple consumer versions for a single application is highly complex, so a full recreation is required to ensure reliability.

Recommended Management Flows

Since direct updates are unavailable, please use the following sequences for management tasks:

1. To Update or Remove a Webhook

To ensure consistency, you must follow this sequence:

Step 1: Disable — Use the /disable endpoint to stop new events from being queued.
Step 2: Delete — Remove the configuration entirely.
Step 3 (Update only): Create — Generate a new version with your updated filters or URL.

2. To Update or Remove an Application

Managing an application requires clearing its associated resources first:

Step 1: Remove Webhooks — Disable and delete all webhooks connected to the application.
Step 2: Delete Application — Call the delete endpoint for the application itself.
Step 3 (Update only): Create Application — Create a new application to generate a fresh configuration and security secret.

Testing with Postman

To simplify development and testing, you can use the provided Postman files to execute these flows immediately.

Import Files: Import spl-webhooks.postman_collection.json and webhooks_env.postman_environment.json into your Postman workspace.
Configure Environment: Update the webhooks_env variables, specifically your tenant, webhooks_integration_client_id, and webhooks_integration_client_secret, to match your Carerix credentials.
Pre-built Requests: The collection is organized into "Webhook API" and "Application API" folders, containing all necessary requests for reading, creating, enabling, disabling, and deleting resources.

When creating a new application, always copy and securely store the secret from the response, as it is required for verifying webhook signatures

Quick Reference: Management Endpoints

Action	Method	Endpoint Path
Enable Webhook	POST	/v1/applications/{appId}/webhooks/{webhookId}/enable
Disable Webhook	POST	/v1/applications/{appId}/webhooks/{webhookId}/disable
Delete Webhook	DELETE	/v1/applications/{appId}/webhooks/{webhookId}
Delete Application	DELETE	/v1/applications/{appId}

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-collections
Import webhook_env Postman environment
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
Authorize using Auth tab in spl-webhooks collection
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"

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

Important: We strongly advise always using conditions in your webhooks to reduce unnecessary notifications (noise) and ensure only relevant updates trigger a webhook.

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

Example 7: Candidate firstname / lastname is Updated

POST

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

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

spl-webhooks.postman_collection.json

webhooks_env.postman_environment.json

Introducing Webhooks in Carerix

GraphQL API

Carerix Marketplace Framework - technical description

Carerix Marketplace Framework - Authentication & SSO Flow