Skip to main content
POST
/
v1
/
webhooks
Create a webhook
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"
      }
    }
  ]
}
'
{
  "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"
  }
}

Documentation Index

Fetch the complete documentation index at: https://developer.folk.app/llms.txt

Use this file to discover all available pages before exploring further.

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

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"
  }
}
You can filter by:
  • The group the person is in
  • The updated attribute
  • The updated attribute and the value of the attribute
// 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.
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"
  }
}
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"
  }
}
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

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"
  }
}
You can filter by:
  • The group the company is in
  • The updated attribute
  • The updated attribute and the value of the attribute
// 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.
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"
  }
}
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

You can filter by:
  • The group the deal is in
  • The group the deal is in and the object type
// 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",
  }
}
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 
// 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
You can filter by:
  • The group the deal is in
  • The group the deal is in and the object type
// 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

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

​
Reminder events

There are no filters available for this event at the moment.
There are no filters available for this event at the moment.
There are no filters available for this event at the moment.
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
Example:
[
  {
    "eventType": "person.created",
    "filter": {
      "groupId": "grp_bc984b3f-0386-434d-82d7-a91eb6badd71"
    }
  }
]

Response

The created webhook.

​
data
object
required

A webhook with a visible signing secret.

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"]