Setting up webhook via API

Following the overview page, you can also setup and edit easily webhooks also via the API.

First, let's explore the methods that supports webhook configuration:

• Create webhook - Create a single webhook within the account
• Get webhook - Retrieve a single webhook by its unique ID
• Get webhooks - Retrieve all webhooks associated with the account
• Update webhook - Update an existing webhook settings
• Delete webhook - Delete a single webhook by its unique ID

Creating/Updating webhook

These methods allow to create and edit webhooks within the account. Let's review the relevant fields in the request body:

• name: The name of the webhook. Can be any name according to your needs.
• url: The endpoint url the payload will be sent to when the event is triggered. Must be a valid https endpoint.
• isDisabled: Determines whether the webhook settings is disabled or enabled upon creation. Default to false (meaning it is enabled).
• featureType: The feature type of the webhook. Current options are: users, forms, time_activity.
• objectId: The ID of the specified object (e.g. for time activities webhook, specify the time clock ID). For users webhook, no need to specify this field.
• eventTypes: The event types under the specified feature type. The list of events is available in the relevant webhook page.

📘

Good to know

The objectId field is not relevant for the users webhooks. There is no need to specify it in that case

Payload example for creating new webhook request

curl --request POST \
     --url https://api.connecteam.com/settings/v1/webhooks \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "isDisabled": false,
  "eventTypes": [
    "user_created",
    "user_deleted"
  ],
  "name": "User webhook",
  "url": "https://testwebhook.test",
  "featureType": "users"
}

Payload example for updating existing webhook request (the webhook id is on the path params)

curl --request PUT \
     --url https://api.connecteam.com/settings/v1/webhooks/webhookId \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "url": "https://newendpoint.test",
  "isDisabled: "true"
}

Get webhook/s

Whether you retrieve a single or multiple webhooks, the structure of the response is similar. Let's review the relevant fields in the response body:

• id: The unique identifier of the webhook. Can be used later for update/delete purposes
• userId: The user who created the webhook (from the UI - the user who created at, from the API - the user who generated the API key)
• timeCreated: The timestamp in UNIX format the webhook was created (if it was modified, this field will not change)
• retryLimit: The number of tries the webhook will be sent from our servers in case of error/no response received. The limit is currently set to 3 and cannot be modified. The retry will be every 60 seconds.

Payload example for retrieving single webhook response

{
  "requestId": "42q3457b-z12c-1136-aeve-e0d433524457",
  "data": {
    "id": 493,
    "name": "Test users webhook",
    "userId": 9170357,
    "timeCreated": 1734074315,
    "url": "https://webhook.site/test",
    "isDisabled": false,
    "featureType": "users",
    "retryLimit": 3,
    "eventTypes": [
      "user_created",
      "user_updated",
      "user_deleted",
      "user_archived",
      "user_restored",
      "user_promoted",
      "user_demoted"
    ]
  }
}