{"revision":"c10276e953456835cdbb1f3a60d58ae1980be353","document":{"id":570,"path":"api-reference/rest-apis/workplace_connector_webhook-api.md","title":"Workplace Connector Webhook API","bundle":null,"doc_type":null,"release":"australia","body":"\n# Workplace Connector Webhook API\n\nThe 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.\n\nThis API runs in the `sn_wsd_wc` namespace. To access this API the Workplace Connectors \\(com.sn\\_wsd\\_wc\\) plugin must be activated.\n\nBefore 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://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/employee-service-management/configure-workplace-connectors.md).\n\nIn 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.\n\nFor additional information on workplace connector webhooks, see [Workplace Connectors](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/employee-service-management/workplace-connectors-landing-page.md).\n\n**Parent Topic:**[REST API reference](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/rest-apis/api-rest.md)\n\n## Workplace Connector Webhook - POST /workplace\\_connector\\_webhook/event\n\nCreates 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.\n\nAfter the endpoint stores the payload, it sets the State field within the Connector Events record to `new`, indicating the payload hasn’t been processed.\n\nA 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`.\n\nThe 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.\n\n**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.\n\n### URL format\n\nVersioned URL: `/api/sn_wsd_wc/{api_version}/workplace_connector_webhook/event`\n\nDefault URL: `/api/sn_wsd_wc/workplace_connector_webhook/event`\n\n**Note:** Available versions are specified in the [REST API Explorer](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/rest-api-explorer/use-REST-API-Explorer.md). For scripted REST APIs there is additional version information on the [Scripted REST Service form](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/rest-api-explorer/c_CustomWebServices.md).\n\n### Supported request parameters\n\n<table class=\"rest_api_path_parameters\"><thead><tr><th>\n\nName\n\n</th><th>\n\nDescription\n\n</th></tr></thead><tbody><tr><td>\n\napi\\_version\n\n</td><td id=\"version-entry-RESTAPI\">\n\nOptional. Version of the endpoint to access. For example, `v1` or `v2`. Only specify this value to use an endpoint version other than the latest. Data type: String\n\n</td></tr></tbody>\n</table><table class=\"rest_api_query_parameters\"><thead><tr><th>\n\nName\n\n</th><th>\n\nDescription\n\n</th></tr></thead><tbody><tr><td>\n\nni.nolog.id\n\n</td><td>\n\nRequired. Sys\\_id of the provider configuration record associated with the hardware that generated the event information.Data type: String\n\nTable: Provider Configuration \\[sn\\_wsd\\_wc\\_provider\\_config\\]\n\n</td></tr><tr><td>\n\ntoken\\_name\n\n</td><td>\n\nName of the security token, such as a user name or other value that identifies the security token. Used for authenticating the request.Data type: String\n\nTable: Provider configuration \\[sn\\_wsd\\_wc\\_provider\\_config\\]\n\n</td></tr><tr><td>\n\ntoken\\_value\n\n</td><td>\n\nValue associated with the security token, such as a password. Used for authenticating the request.Data type: String\n\nTable: Provider configuration \\[sn\\_wsd\\_wc\\_provider\\_config\\]\n\n</td></tr></tbody>\n</table><table class=\"rest_api_request_body\"><thead><tr><th>\n\nName\n\n</th><th>\n\nDescription\n\n</th></tr></thead><tbody><tr><td>\n\n&lt;payload&gt;\n\n</td><td>\n\nName-value pairs of the hardware/sensor-based event data. The names must correspond to the names identified in the BadgingDataHandler extension point.\n\nFor example:\n\n```\n{\n  \"Time zone\": \"(UTC-08:00) Pacific Time (US & Canada)\",\n  \"Event\": \"Access granted\",\n  \"Door\": \"L_SJC005_B1.101_ELEVATOR 2 INT\",\n  \"Side\": \"Reader - In\",\n  \"Cardholder\": \"ninat.salem\",\n  \"First name\": \"Nina T\",\n  \"Last name\": \"Salem\",\n  \"Credential\": \" ninat.salem's credential\",\n  \"Employee ID (Cardholder)\": \"10097\",\n  \"Event timestamp\": \"11/07/2022 00:56:57\"\n}\n```\n\nYou 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.\n\n**Note:** Ensure that any provided timestamp adheres to ISO 8601 formatting to avoid any issues with date parsing.\n\nData type: JSON object\n\n</td></tr></tbody>\n</table>### Headers\n\nThe 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://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/rest-api-explorer/c_RESTAPI.md).\n\n|Header|Description|\n|------|-----------|\n|Accept|Data format of the response body. Only supports **application/json**.|\n|Content-Type|Data format of the request body. Only supports **application/json**.|\n\n|Header|Description|\n|------|-----------|\n|None| |\n\n### Status codes\n\nThe 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://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/rest-api-explorer/c_RESTAPI.md).\n\n|Status code|Description|\n|-----------|-----------|\n|200|Successful. The request was successfully processed.|\n|400|Bad Request. A bad request type or malformed request was detected.|\n|401|Unauthorized. The user credentials are incorrect or have not been passed.|\n|404|Not found. The requested item wasn't found.|\n|500|Internal server error. An unexpected error occurred while processing the request. The response contains additional information about the error.|\n\n### Response body parameters\n\n<table><thead><tr><th>\n\nName\n\n</th><th>\n\nDescription\n\n</th></tr></thead><tbody><tr><td>\n\nerror\n\n</td><td>\n\nDescription of any error that occurred during the processing of the data.Data type: Object\n\n```\n\"error\": {\n  \"detail\": \"String\",\n  \"message\": \"String\"\n\"status\": \"String\"\n}\n```\n\n</td></tr><tr><td>\n\nerror.detail\n\n</td><td>\n\nInformation that provides details about the error.Data type: String\n\n</td></tr><tr><td>\n\nerror.message\n\n</td><td>\n\nError message.Data type: String\n\n</td></tr><tr><td>\n\nstatus\n\n</td><td>\n\nStatus of the endpoint processing.Possible values:\n\n-   failure: Endpoint failed. Refer to the **error** object for additional details.\n-   success: Endpoint completed successfully. Record was added.\n\nData type: String\n\n</td></tr></tbody>\n</table>### cURL request\n\nThe 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.\n\n```\ncurl http://instance.servicenow.com/api/sn_wsd_wc/v1/workplace_connector_webhook/event?token_name=token&ni.nolog.id=8e666cb0a3053110bc6e146546fcdad1&token_value=babugosha  \\\n--request POST \\\n--header \"Accept:application/json\" \\\n--header \"Content-Type:application/json\" \\\n--data --data \"{\n  \\\"Time zone\\\": \\\"(UTC+02:00) Jerusalem\\\",\n  \\\"Event\\\": \\\"Access granted\\\",\n  \\\"Door\\\": \\\"L_TLV001_A3.07_KITCHEN AREA INT\\\",\n  \\\"Side\\\": \\\"Reader - In\\\",\n  \\\"Cardholder\\\": \\\" ninat.alem\\\",\n  \\\"First name\\\": \\\" Nina T\\\",\n  \\\"Last name\\\": \\\" Salem\\\",\n  \\\"Credential\\\": \\\" ninat.salem's credential\\\",\n  \\\"Employee ID (Cardholder)\\\": 10097,\n  \\\"Event timestamp\\\": \\\"11/07/2022 10:57:24\\\"\n}\n{\n  \\\"Time zone\\\": \\\"(UTC+02:00) Jerusalem\\\",\n  \\\"Event\\\": \\\"Access granted\\\",\n  \\\"Door\\\": \\\"L_TLV003_A4.07_FRONT ENT\\\",\n  \\\"Side\\\": \\\"Reader - In\\\",\n  \\\"Cardholder\\\": \\\" joe.blue\\\",\n  \\\"First name\\\": \\\" Joe\\\",\n  \\\"Last name\\\": \\\" Blue\\\",\n  \\\"Credential\\\": \\\" joe.blue's credential\\\",\n  \\\"Employee ID (Cardholder)\\\": 24098,\n  \\\"Event timestamp\\\": \\\"11/07/2022 10:59:33\\\"\n}\"\n```\n\nResponse:\n\n```\n// Successful response\n{\n  \"staus\": \"success\"\n}\n\n// Error response\n{\n  \"error\": {\n    \"message\": \"Events request is invalid. Events query parms incomplete, some fields are missing\",\n    \"detail\": \"Missing fields: token_name, token_value\"\n  }\n  \"status\": \"failure\"\n}\n```\n\n"}}