---
sourceDocument: Xanadu API Reference
sourceDocumentLink: https://servicenow-prod.fluidtopics.net/r/xanadu/api-reference

 Release :

    - xanadu

ft:locale :

    - en-US

ft:publication_title :

    - Xanadu API Reference

ft:clusterId :

    - crapiref

bundleId :

    - crapiref

workflow :

    - Creator


---

# Workplace Connector Webhook API

# Workplace Connector Webhook API {#ariaid-title1}

* Release version: Xanadu
* 
* Updated August 1, 2024
* 
* ![](https://www.servicenow.com/docs/portal-asset/ico-clock) 4 minutes to read

The Workplace Connector Webhook API is a generic interface that enables data from different kinds of workplace hardware or sensors (such as badging systems or occupancy sensors) to be stored in Workplace
Service Delivery tables.
This API runs in the `sn_wsd_wc` namespace. To access this API the Workplace Connectors (com.sn_wsd_wc) plugin must be activated.

Before calling this API, you must configure records in the Connector Configuration \[sn_wsd_wc_connector_config\] and Provider Configuration \[sn_wsd_wc_provider_config\] tables. For information on how to configure these records, see [Configure Workplace Connectors](https://www.servicenow.com/docs/access?context=configure-workplace-connectors&version=xanadu&pubname=xanadu-employee-service-management&ft:locale=en-US).

In addition, you must set up an extension point that defines the data conversion/mapping from the hardware/sensor-based event payload to the target ServiceNow table, such as the Employee Attendance Data \[sn_wsd_wc_employee_attendance_data\] table.

For additional information on workplace connector webhooks, see [Workplace Connectors](https://www.servicenow.com/docs/access?context=workplace-connectors-landing-page&version=xanadu&pubname=xanadu-employee-service-management&ft:locale=en-US).

## Workplace Connector Webhook - POST /workplace_connector_webhook/event {#ariaid-title2}

Creates a record in the Connector Events \[sn_wsd_wc_connector_events\] table and then stores the hardware/sensor-based event data passed in the endpoint's payload into the Payload field of that record.
After the endpoint stores the payload, it sets the State field within the Connector Events record to `new`, indicating the payload hasn't been processed.

A scheduled job locates the new badging records in the Connector Events table and transforms and writes them to the Employee Attendance Data \[sn_wsd_wc_employee_attendance_data\] table. The State field is then set to
`processed`.

The mapping of the data between the payload data in the Connector Events record and the Employee Attendance Data record is defined in an extension point. This extension point is identified in the Extension Point Definition field in
the associated Connector Configuration \[sn_wsd_wc_connector_config\] table. For this endpoint, this is the BadgingDataHandler extension point.  
Note:  
Records in the Connector Events table in the `processed` state are purged after two days from the creation date. Records in the `error` state are purged after seven days from the date of creation. Records in the `new `state are never purged.

### URL format

Versioned URL: /api/sn_wsd_wc/v1/workplace_connector_webhook/event

Default URL: /api/sn_wsd_wc/workplace_connector_webhook/event

### Supported request parameters

{#work_conn_web-POST-event__entry__2}{#work_conn_web-POST-event__version-not_optional-RESTAPI}

| Name | Description |
|-|-|
| api_version | Optional. Version of the endpoint to access. For example, <kbd class="ph userinput">v1</kbd> or <kbd class="ph userinput">v2</kbd>. Only specify this value to use an endpoint version other than the latest. Data type: String |
[Table 1. Path parameters]

{#work_conn_web-POST-event__entry__6}

| Name | Description |
|-|-|
| ni.nolog.id | Required. Sys_id of the provider configuration record associated with the hardware that generated the event information. Located in the Provider Configuration \[sn_wsd_wc_provider_config\] table. Data type: String |
| token_name | Name of the security token, such as a user name or other value that identifies the security token. Used for authenticating the request. Located in the Provider configuration \[sn_wsd_wc_provider_config\] table. Data type: String |
| token_value | Value associated with the security token, such as a password. Used for authenticating the request. Located in the Provider configuration \[sn_wsd_wc_provider_config\] table. Data type: String |
[Table 2. Query parameters]

{#work_conn_web-POST-event__entry__14}

| Name | Description |
|-|-|
| \<payload\> | Name-value pairs of the hardware/sensor-based event data. The names must correspond to the names identified in the BadgingDataHandler extension point. For example: { "Time zone": "(UTC-08:00) Pacific Time (US & Canada)", "Event": "Access granted", "Door": "L_SJC005_B1.101_ELEVATOR 2 INT", "Side": "Reader - In", "Cardholder": "ninat.salem", "First name": "Nina T", "Last name": "Salem", "Credential": " ninat.salem's credential", "Employee ID (Cardholder)": "10097", "Event timestamp": "11/07/2022 00:56:57" } You can pass multiple event's data within a single endpoint call. Pass each event's data in a separate object. Each event's data is stored in a separate Employee Attendance Data record. Note: Ensure that any provided timestamp adheres to ISO 8601 formatting to avoid any issues with date parsing. Data type: JSON object |
[Table 3. Request body parameters (XML or JSON)]

### Headers

The following request and response headers apply to this HTTP
action only, or apply to this action in a distinct way. For a list of general headers used
in the REST API, see [Supported REST API headers](https://servicenow-prod.fluidtopics.net/2vuQj3~2s_niNXyXhrbRZA "REST (REpresentational State Transfer) is a simple stateless architecture that provides standards between computer systems on the web, making it easier for them to communicate with each other.").
{#work_conn_web-POST-event__entry__18}{#work_conn_web-POST-event__accept-JSON-only-entry-RESTAPI}{#work_conn_web-POST-event__content_type-JSON-only-entry-RESTAPI}

| Header | Description |
|-|-|
| Accept | Data format of the response body. Only supports application/json. |
| Content-Type | Data format of the request body. Only supports application/json. |
[Table 4. Request headers]

{#work_conn_web-POST-event__entry__24}

| Header | Description |
|-|-|
| None |   |
[Table 5. Response headers]

### Status codes

The following status codes apply to this HTTP action. For a
list of possible status codes used in the REST API, see [REST API HTTP response
codes](https://servicenow-prod.fluidtopics.net/2vuQj3~2s_niNXyXhrbRZA "REST (REpresentational State Transfer) is a simple stateless architecture that provides standards between computer systems on the web, making it easier for them to communicate with each other.").
{#work_conn_web-POST-event__table_fqw_2fg_xyb__entry__2}{#work_conn_web-POST-event__entry-200-status-code}{#work_conn_web-POST-event__entry-400-status-code}{#work_conn_web-POST-event__entry-401-status-code}{#work_conn_web-POST-event__entry-404-status-code}{#work_conn_web-POST-event__entry-500-status-code}

| Status code | Description |
|-|-|
| 200 | Successful. The request was successfully processed. |
| 400 | Bad Request. A bad request type or malformed request was detected. |
| 401 | Unauthorized. The user credentials are incorrect or have not been passed. |
| 404 | Not found. The requested item wasn't found. |
| 500 | Internal server error. An unexpected error occurred while processing the request. The response contains additional information about the error. |
[Table 6. Status codes]

{#work_conn_web-POST-event__table_fqw_2fg_xyb}

### Response body parameters

{#work_conn_web-POST-event__entry__40}

| Name | Description |
|-|-|
| error | Description of any error that occurred during the processing of the data. Data type: Object "error": { "detail": "String", "message": "String" "status": "String" } |
| error.detail | Information that provides details about the error. Data type: String |
| error.message | Error message. Data type: String |
| status | Status of the endpoint processing. Possible values: * failure: Endpoint failed. Refer to the error object for additional details. * success: Endpoint completed successfully. Record was added. {#work_conn_web-POST-event__ul_lkc_q2g_xyb} Data type: String |
[ ]

### cURL request

The following code example shows how to call this endpoint to add multiple card reader events to the Connector Events table. Before processing the request, the request is authenticated.

    curl http://instance.servicenow.com/api/sn_wsd_wc/v1/workplace_connector_webhook/event?token_name=token&ni.nolog.id=8e666cb0a3053110bc6e146546fcdad1&token_value=babugosha  \
    --request POST \
    --header "Accept:application/json" \
    --header "Content-Type:application/json" \
    --data --data "{
      \"Time zone\": \"(UTC+02:00) Jerusalem\",
      \"Event\": \"Access granted\",
      \"Door\": \"L_TLV001_A3.07_KITCHEN AREA INT\",
      \"Side\": \"Reader - In\",
      \"Cardholder\": \" ninat.alem\",
      \"First name\": \" Nina T\",
      \"Last name\": \" Salem\",
      \"Credential\": \" ninat.salem's credential\",
      \"Employee ID (Cardholder)\": 10097,
      \"Event timestamp\": \"11/07/2022 10:57:24\"
    }
    {
      \"Time zone\": \"(UTC+02:00) Jerusalem\",
      \"Event\": \"Access granted\",
      \"Door\": \"L_TLV003_A4.07_FRONT ENT\",
      \"Side\": \"Reader - In\",
      \"Cardholder\": \" joe.blue\",
      \"First name\": \" Joe\",
      \"Last name\": \" Blue\",
      \"Credential\": \" joe.blue's credential\",
      \"Employee ID (Cardholder)\": 24098,
      \"Event timestamp\": \"11/07/2022 10:59:33\"
    }"

Response:

    // Successful response
    {
      "staus": "success"
    }

    // Error response
    {
      "error": {
        "message": "Events request is invalid. Events query parms incomplete, some fields are missing",
        "detail": "Missing fields: token_name, token_value"
      }
      "status": "failure"
    }