---
title: "Add Webhook"
method: POST
path: "/management/hooks"
tags: ["Webhooks"]
---

# Add Webhook

`POST /management/hooks`

## Request

- Base URL: `https://api.paychex.com`
- URL: `https://api.paychex.com/management/hooks`
- Auth: none declared
- TypeScript: <https://skmtc.dev/paychex/apis/external-api/docs/management/hooks/post.ts> (a function with typed inputs; its response is checked against the schema)

<h3>Add a webhook for the calling application.</h3><p>When registering a webhook, you will need to provide your own URI in the request body (see our <a href='https://developer.paychex.com/resources/webhooks'>full webhook documention here</a> on how to configure your URI). The newly registered webhook will send notifications to this endpoint as JSON payloads which vary by domain. Please configure your endpoint to accept the relevant payloads. To see an example payload for each domain, please refer to the "Callbacks" tab.</p>

## Request body

- WebhookRequest: This resource is for registering/unregistering webhooks.
  - `hookId` string: The unique identifier associated with this webhook. Not required for Posting.
  - `uri` string, required: Enter a valid URL for the webhook to receive events.
  - `companyId` string: ID associated with desired company that will receive the webhook notifications. NOTE: If no Company ID is provided in the POST, then all companies linked to the app will receive notifications.
  - `authentication` Authentication1, required: Required Authentication object is going to be different based on each authType. <br />* NO_AUTH doesn't have any other fields in authentication object <br />* BASIC_AUTH needs 2 fields: username and password <br />* APIKEY requires the field: apiKey <br />* OAUTH2 requires 5 fields: tokenUrl, clientId, clientSecret, grantType, contentType <br />* OAUTH2_BASIC requires 5 fields: tokenUrl, clientId, clientSecret, grantType, contentType
    - `authType` 'NO_AUTH' | 'BASIC_AUTH' | 'API_KEY' | 'OAUTH2' | 'OAUTH2_BASIC', required: The authorization method used to authorize callers to your webhook url.
    - `apiKey` string: The API key required for API_KEY authorization.
    - `username` string: The username required for BASIC_AUTH authorization.
    - `password` string: The password required for BASIC_AUTH authorization.
    - `tokenUrl` string: The URL used to obtain an access token for OAUTH2 or OAUTH2_BASIC authorization.
    - `clientId` string: The client ID required by OAUTH2 and OAUTH2_BASIC authorization.
    - `clientSecret` string: The client secret required by OAUTH2 and OAUTH2_BASIC authorization.
    - `grantType` string: The grant type used to acquire an access token by OAUTH2 and OAUTH2_BASIC authorization.
    - `contentType` string: The content type to use in the token request for OAUTH2 and OAUTH2_BASIC authorization.
  - `domains` string[], required: List of available domains to register to. Refer to webhook documentation https://developer.paychex.com/documentation#operation/domains.
  - `links` Link[]
    - `rel` string
    - `href` string
    - `hreflang` string
    - `media` string
    - `title` string
    - `type` string
    - `deprecation` string
    - `profile` string
    - `name` string

## Response `201`

Webhook successfully created.

- WebhookResponse
  - `hookId` string
  - `companyId` string
  - `uri` string
  - `authType` string
  - `createdDate` string, date-time
  - `active` boolean
  - `domains` string[]

## Other responses

- `400`: Please add the required attribute. (API-46), Please provide a hookid without special characters. (API-22)
- `401`: Unauthorized
- `403`: User does not have access to this resource. (API-2)
- `404`: Invalid resource ID (API-7)
- `405`: Unsupported method type (API-59)
- `500`: Internal Server Error.

---

[API](https://skmtc.dev/paychex/apis/external-api.md) - [All operations](https://skmtc.dev/paychex/apis/external-api/llms.txt) - [OpenAPI document](https://skmtc.dev/paychex/apis/external-api/revisions/07161d3e073f?raw)