Skip to main content

Documentation Index

Fetch the complete documentation index at: https://developer.karmacheck.com/llms.txt

Use this file to discover all available pages before exploring further.

The KarmaCheck system emits events for different activities. To know when these events happen, you can use webhooks to get automatic updates. For instance, services performed by KarmaCheck involve different turnaround times, so you might want to receive real-time notifications about events related to each service. These notifications are sent as webhooks containing a JSON payload with information about the event. By subscribing to webhooks, you’ll know when to fetch the latest data, enabling you to respond to events in real time.

​
Subscriptions

You can set up a webhook for your company, which will deliver events for all groups within the company. If you need webhooks to be sent to different URLs for some or all groups, webhooks can also be configured for these individual groups. When a webhook is configured for a specific group, events for that group are sent to the group webhook subscription only and not the company webhook subscription. You can subscribe to webhooks in the KarmaCheck sandbox dashboard. You will need the following information:
  • A URL that’s configured to handle incoming HTTPS POST requests. KarmaCheck will send notifications to this URL whenever relevant events occur.
  • A username and password that you want to associate with the webhook. Although these values are optional, we recommend setting up a username and password as a best practice.
  • The event types that you want to subscribe to. See Events for a list of supported events.
  • The group ID of a group within your company only if you want to configure your webhook URL to receive events occurring for just that specific group. Unless specified, a webhook is usually configured to deliver events occurring for all groups within a company.
The webhook subscription link above is for your sandbox account. Use the production domain to subscribe to webhooks in production.

​
Webhook structure

All webhooks are delivered over HTTPS and include the following properties in a JSON payload: 
{
  "messageId": "string — the unique identifier of the event notification",
  "event": "string — the webhook event being delivered",
  "apiTrackingCode": "string | null — an identifier for tracking a case",
  "apiTrackingUser": "string | null — an identifier for tracking a case",
  "username": "string | null — the username for authenticating the webhook request",
  "password": "string | null — the password for authenticating the webhook request",
  "eventObject": "object — various properties with information related to the event"
}
The following is an example of a webhook request that you’ll receive when an event occurs: 
POST /webhook-endpoint HTTP/1.1
Connection: close
Host: example.com
Content-Length: 1902
User-Agent: KarmaCheck WebHook 2.0
Content-Type: application/json
Accept: application/json, text/plain, */*

{
  "messageId": "72fcd5f8-fb13-7de2-2152-e88e5257aff4",
  "event": "case.statuschange",
  "apiTrackingCode": null,
  "apiTrackingUser": null,
  "username": null,
  "password": null,
  "eventObject": {
    ...
  }
}

​
Authenticating webhooks

You can supply a username and password when configuring a webhook subscription. If configured, KarmaCheck sends those values in the payload of every webhook event. This enables you to verify the authenticity of incoming webhook requests.

​
Responding to webhooks

To confirm receipt of a webhook, your webhook endpoint must respond with a 2xx HTTP status code as quickly as possible. Any response codes outside of this range, including 3xx codes, will indicate that you did not receive the webhook. Any other information returned does not get processed.

​
Retries

If a webhook call is not successfully acknowledged, KarmaCheck will attempt to resend the webhook once more after 2 minutes. After this attempt, no further retries will be made.

​
Events

The following events can trigger webhooks. KarmaCheck can configure webhooks to send either or both types of event notifications to your configured URL.
EventDescription
case.statuschangeThe status of a case has changed.
casedata.statuschangeThe status of a service (case data) has changed.
Additional events might be supported in the future. New event types will follow the same pattern as existing ones. As a best practice, use all event notifications as indicators to fetch the latest data for a case or service. The sections below provide additional best practices for event handling.

​
Order of events

Each supported event occurs multiple times during a case’s lifecycle. As an example with the case.statuschange event, the status of a case involving a candidate-provided PII flow could change like so:
Event orderCase statusDescription
1caseStatus: “Pending” / secondaryStatus: “Waiting for Authorization”Invitation sent to candidate
2caseStatus: “Pending” / secondaryStatus: “Authorization in Progress”Candidate started onboarding
3caseStatus: “Pending” / secondaryStatus: nullCase is processing
4caseStatus: “Complete” / secondaryStatus: nullCase is complete, with all screenings cleared
Out-of-order events: Due to network latency and other factors that might affect delivery timing, KarmaCheck does not guarantee that you will receive notifications in the order that events occur. Therefore, your endpoint should not rely on the delivery of these events in the listed order. Instead, you should fetch the latest details of a case using GET /case/id/{caseId} whenever you receive the case.statuschange event.

​
Duplicate events

Webhook endpoints might occasionally receive the same notification more than once if multiple events occur within a short period of time. One way to account for duplicate events is to log the events that you have processed so that you can avoid reprocessing them. For example, when receiving a case.statuschange event, compare the following properties to those of your logged events:
  • id: The case ID
  • caseStatusId and secondaryCaseStatusId: The case status
  • modStamp: The timestamp for the case modification

​
Missed events

Some issues that might occur, such as server errors, could lead to missed webhook notifications. To account for the possibility of missed events, you can build a function to check if a type of event notification hasn’t been received for a specific length of time. When this happens, fetch the latest data related to the missed event.