Create a webhook

Creates a new webhook listening to workspace events.

POST /v1/webhooks

Create a webhook

cURL

curl --request POST \
  --url https://api.folk.app/v1/webhooks \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "My app integration",
  "targetUrl": "https://my-app.com/webhook",
  "subscribedEvents": [
    {
      "eventType": "person.created",
      "filter": {
        "groupId": "grp_bc984b3f-0386-434d-82d7-a91eb6badd71"
      }
    }
  ]
}
'

200

{
  "data": {
    "id": "wbk_8c18c158-d49e-4ad4-90d4-2b197688bac7",
    "name": "My app integration",
    "targetUrl": "https://my-app.com/webhook",
    "subscribedEvents": [
      {
        "eventType": "person.created",
        "filter": {}
      }
    ],
    "signingSecret": "whsec_QWFSUzl1QUVoQW1kdWtpTnJRTUFpbXNlZmxLTg==",
    "status": "active",
    "createdAt": "2025-07-17T09:00:00.000Z"
  }
}

Create a webhook to be notified about events that occur in the workspace.

To learn more about webhooks, how to set them up and receive notifications, check out the webhooks guide.

Available events

You can find the list of available events in the webhook events and payloads guide.

Filters

You can add filters to events in order to narrow down the notifications you receive.

Filters allow you to achieve advanced workflow capabilities, such as:

• Only receive notifications when a person is added to a specific group.
• Only receive notifications when a company is moved to a specific pipeline status.
• Only receive notifications when a deal from a specific group is updated.

Each event type has a different set of filters that can be used. Click on the event types below to see the filters available.

Filters are only available through the API. If you add filters and then update the events from the settings page, the filters will be lost.

Person events

person.created

You can filter by the group the person is added to.

// Notify only if the person is created in a group
// with the ID grp_bc984b3f-0386-434d-82d7-a91eb6badd71
{
  "eventType": "person.created",
  "filter": {
    "groupId": "grp_bc984b3f-0386-434d-82d7-a91eb6badd71"
  }
}

person.updated

You can filter by:

• The group the person is in
• The updated attribute
• The updated attribute and the value of the attribute

Filter by group

// Notify only if the person is updated while in a group
// with the ID grp_bc984b3f-0386-434d-82d7-a91eb6badd71
{
  "eventType": "person.updated",
  "filter": {
    "groupId": "grp_bc984b3f-0386-434d-82d7-a91eb6badd71"
  }
}

Only the following attributes can be filtered:

• firstName
• lastName
• birthday
• jobTitle
• description - You cannot provide a value for this attribute
• addresses
• emails
• phones
• urls
• customFieldValues

When passing a value for these fields, you must provide the value in the correct format. Refer to the update person documentation for more information.

person.deleted

You can filter by the group the person is removed from.

// Notify only if the person is deleted while in a group
// with the ID grp_bc984b3f-0386-434d-82d7-a91eb6badd71
{
  "eventType": "person.deleted",
  "filter": {
    "groupId": "grp_bc984b3f-0386-434d-82d7-a91eb6badd71"
  }
}

person.groups_updated

You can filter by the group the person is added to or removed from.

// Notify only if the person is added to or removed from the group
//  with the ID grp_bc984b3f-0386-434d-82d7-a91eb6badd71
{
  "eventType": "person.groups_updated",
  "filter": {
    "groupId": "grp_bc984b3f-0386-434d-82d7-a91eb6badd71"
  }
}

person.workspace_interaction_metadata_updated

You can filter by the group the person is in.

// Notify only if the person's workspace interaction metadata
// is updated while in a group with the ID grp_bc984b3f-0386-434d-82d7-a91eb6badd71
{
  "eventType": "person.workspace_interaction_metadata_updated",
  "filter": {
    "groupId": "grp_bc984b3f-0386-434d-82d7-a91eb6badd71"
  }
}

Company events

company.created

You can filter by the group the company is added to.

// Notify only if the company is created in a group
// with the ID grp_bc984b3f-0386-434d-82d7-a91eb6badd71
{
  "eventType": "company.created",
  "filter": {
    "groupId": "grp_bc984b3f-0386-434d-82d7-a91eb6badd71"
  }
}

company.updated

You can filter by:

• The group the company is in
• The updated attribute
• The updated attribute and the value of the attribute

Filter by group

// Notify only if the company is updated while in a group
// with the ID grp_bc984b3f-0386-434d-82d7-a91eb6badd71
{
  "eventType": "company.updated",
  "filter": {
    "groupId": "grp_bc984b3f-0386-434d-82d7-a91eb6badd71"
  }
}

Only the following attributes can be filtered:

• name
• description - You cannot provide a value for this attribute
• addresses
• emails
• phones
• urls
• fundingRaised
• lastFundingDate
• foundationYear
• employeeRange
• industry
• customFieldValues

When passing a value for these fields, you must provide the value in the correct format. Refer to the update company documentation for more information.

company.deleted

You can filter by the group the company is removed from.

// Notify only if the company is deleted while in a group
// with the ID grp_bc984b3f-0386-434d-82d7-a91eb6badd71
{
  "eventType": "company.deleted",
  "filter": {
    "groupId": "grp_bc984b3f-0386-434d-82d7-a91eb6badd71"
  }
}

company.groups_updated

You can filter by the group the company is added to or removed from.

// Notify only if the company is added to or removed from the group
//  with the ID grp_bc984b3f-0386-434d-82d7-a91eb6badd71
{
  "eventType": "company.groups_updated",
  "filter": {
    "groupId": "grp_bc984b3f-0386-434d-82d7-a91eb6badd71"
  }
}

Deal events

object.created

You can filter by:

• The group the deal is in
• The group the deal is in and the object type

Filter by group

// Notify only if the deal is created while in a group
// with the ID grp_bc984b3f-0386-434d-82d7-a91eb6badd71
{
  "eventType": "object.created",
  "filter": {
    "groupId": "grp_bc984b3f-0386-434d-82d7-a91eb6badd71",
  }
}

object.updated

You can filter by:

• The group the deal is in

• The group the deal is in and the object type

• Group, object type and the updated attribute

• Group, object type, the updated attribute and the value of the attribute

Filter by group

// Notify only if the deal is updated while in a group
// with the ID grp_bc984b3f-0386-434d-82d7-a91eb6badd71
{
  "eventType": "object.updated",
  "filter": {
    "groupId": "grp_bc984b3f-0386-434d-82d7-a91eb6badd71",
  }
}

Only the following attributes can be filtered:

• name
• customFieldValues

object.deleted

You can filter by:

• The group the deal is in
• The group the deal is in and the object type

Filter by group

// Notify only if the deal is deleted from the group
// with the ID grp_bc984b3f-0386-434d-82d7-a91eb6badd71
{
  "eventType": "object.deleted",
  "filter": {
    "groupId": "grp_bc984b3f-0386-434d-82d7-a91eb6badd71",
  }
}

Note events

note.created

There are no filters available for this event at the moment.

note.updated

There are no filters available for this event at the moment.

note.deleted

There are no filters available for this event at the moment.

Reminder events

reminder.created

There are no filters available for this event at the moment.

reminder.updated

There are no filters available for this event at the moment.

reminder.deleted

There are no filters available for this event at the moment.

reminder.triggered

There are no filters available for this event at the moment.

Authorizations

Authorization · string · header · required

API key for authentication

Body

application/json

name · string · required

A friendly name for the webhook.

Maximum string length: 255

Example:

"My app integration"

targetUrl · string<uri> · required

The URL of the webhook. It must be a publicly accessible URL using the HTTP or HTTPS protocol.

Maximum string length: 2048

Example:

"https://my-app.com/webhook"

subscribedEvents · object[] · required

The events the webhook is subscribed to, with optional filters.

Required array length: 1 - 20 elements

Show child attributes

Example:

[
  {
    "eventType": "person.created",
    "filter": {
      "groupId": "grp_bc984b3f-0386-434d-82d7-a91eb6badd71"
    }
  }
]

Response

200

application/json

The created webhook.

data · object · required

A webhook with a visible signing secret.

Show child attributes

Example:

{
  "id": "wbk_8c18c158-d49e-4ad4-90d4-2b197688bac7",
  "name": "My app integration",
  "targetUrl": "https://my-app.com/webhook",
  "subscribedEvents": [
    {
      "eventType": "person.created",
      "filter": {}
    }
  ],
  "signingSecret": "whsec_QWFSUzl1QUVoQW1kdWtpTnJRTUFpbXNlZmxLTg==",
  "status": "active",
  "createdAt": "2025-07-17T09:00:00.000Z"
}

deprecations · string[]

Example:

["This field is deprecated"]