# ServiceNow

ServiceNow is a cloud-based platform that provides IT service management (ITSM) and business process automation tools. It enables organizations to streamline and automate various workflows, such as IT operations, customer service, and HR.

***

### Prerequisites

<table><thead><tr><th width="252">Item</th><th>Description</th></tr></thead><tbody><tr><td><strong>ServiceNow Account</strong></td><td>Account with the Administrator role</td></tr><tr><td><strong>ServiceNow Application Registration</strong></td><td><a href="https://docs.servicenow.com/bundle/washingtondc-security-management/page/product/secops-integration-sir/secops-integration-splunk-addon/task/configure-application-registry-splunk.html">Registration</a> that enables Apono to use OAuth authorization<br><br>Be sure to copy the <code>client_id</code> and <code>client_secret</code>. You will use these values to generate the ServiceNow API token.</td></tr><tr><td><strong>ServiceNow Information</strong></td><td><p>Information for the ServiceNow instance:</p><ul><li>Instance ID</li><li>Username</li><li>Password</li></ul><p><br>Follow these steps to retrieve the ServiceName information:</p><ol><li>On the <a href="https://developer.servicenow.com/dev.do#!/home">ServiceNow Developers home page</a>, click your account icon <strong>> Manage instance password</strong>. The <strong>Manage instance password</strong> popup window appears.</li><li>Copy the <strong>Instance name</strong>, <strong>Username</strong>, and <strong>Password</strong>.</li></ol></td></tr><tr><td><strong>ServiceNow API token</strong></td><td><a href="https://support.servicenow.com/kb?id=kb_article_view&#x26;sysparm_article=KB0778194">Credential</a> generated with a username and a password and used when making requests to the ServiceNow API.</td></tr></tbody></table>

***

### Configure a webhook

Follow these steps to configure a ServiceNow webhook:

1. On the [**Webhooks**](https://app.apono.io/webhooks) page, click **Add Webhook**. The **Add Webhook** page appears.
2. Click **Request Webhook**.
3. Enter a unique, alphanumeric, user-friendly **Request Webhook Name** for identifying this webhook.
4. Click the **Status** toggle to **Active**.
5. From the **Method** dropdown menu, select a REST method.
6. In the **URL** field, enter *https\://\<SERVICENOW\_INSTANCE\_ID>.service-now\.com/api/now/table/incident*.\
   \
   Be sure to replace `<SERVICENOW_INSTANCE_ID>` with the instance ID.

{% hint style="warning" %}
The webhook URL **must adhere** to the following requirements:

* Uses the HTTPS protocol
* Does **not** specify any custom ports
  {% endhint %}

7. In the **Body Template** field, construct a JSON body for the webhook payload.

```json
{
  "caused_by": "{{ data.requester.name }}",
  "short_description": "{{ data.access_groups.[0].integration.name }}",
  "cause": "{{ event_type }}",
  "description": "{ "event_type": "{{ event_type }}", "event_time": "{{ event_time }}", "id": "{{ data.id }}", "friendly_id": "{{ data.friendly_id }}", "requester_id": "{{ data.requester.id }}", "requester_name": "{{ data.requester.name }}", "requester_email": "{{ data.requester.email }}", "justification": "{{ data.justification }}", "creation_date": "{{ data.creation_date }}", "access_flow_id": "{{ data.access_flow.id }}", "access_flow_name": "{{ data.access_flow.name }}", "access_bundle_id": "{{ data.access_bundle.id }}", "access_bundle_name": "{{ data.access_bundle.id }}", "access_groups_integration_name": "{{ data.access_groups.[0].integration.name }}", "access_groups_integration_type": "{{ data.access_groups.[0].integration.type }}" }",
  "reopened_by": "apono app"
}
```

{% hint style="success" %}
Click **View event's payload schema** to reveal the payload schema and available data fields. You can also refer to the [Webhook Payload Schema Reference](https://docs.apono.io/docs/webhook-integrations/webhook-payload-references/webhook-payload-schema-reference) to read the descriptions of each data field.
{% endhint %}

8. Under **Headers**, use the following **Key** and **Value** to set the header. Be sure to replace `<SERVICENOW_TOKEN>` with the ServiceNow API token.

| Key             | Value                         |
| --------------- | ----------------------------- |
| *Authorization* | *Bearer \<SERVICENOW\_TOKEN>* |

9. From the **Triggers** dropdown menu, select one or more of the following event triggers, which correspond to Apono access request statuses:
   * **RequestCreated**
   * **RequestApproved**
   * **RequestExpired**
   * **RequestFailed**
   * **RequestGranted**
   * **RequestRejected**
10. Under **Filters**, define one or several filter from the listed dropdown menus.

{% hint style="info" %}
Filters empower admins to control the data transmitted via webhooks, minimizing the amount of data third-party tools receive and reducing unnecessary clutter.

**Examples**:

* Send only production requests to your admins' Slack channel.
* Trigger Okta workflows for events from specific integrations or resource types.
* Open a ticket in Jira or ServiceNow for manually approved requests.
  {% endhint %}

11. (Optional) In the **Timeout in seconds** field, enter the duration in seconds to wait before marking the request as failed.
12. (Optional) Define **Response Validators** to verify that the response from the webhook meets specified criteria:
    1. Click **+ Add**. A row of settings appears.
    2. Starting with *$.data.*, enter the **Json Path** of the JSON parameter.
    3. In the **Expected Values** field, enter a value and press the Enter key on your keyboard.
    4. Repeat step **c** to add several expected values.
    5. Repeat steps **a-d** to add multiple response validators.
13. Click **Test** to generate a test event to trigger your webhook. A **Test successful** or **Test failed** response status will appear at the bottom of the page. A successful test will send mock data to the target system.

{% hint style="success" %}
For more information about the test, click **View Invocation Data**. A panel opens revealing the request, response, and other relevant details.

Should your test fail, view these tips to [troubleshoot your webhook](https://docs.apono.io/docs/webhook-integrations/troubleshoot-a-webhook).
{% endhint %}

14. Click **Save Webhook**.

The new webhook appears in the **Webhooks** table. Active webhooks are preceded by a green dot. Inactive webhooks are preceded by a white dot.

Apono access request logs will be sent to ServiceNow based on the triggers you have selected.