Skip to main content
Beebole’s outgoing webhooks let you subscribe to real-time notifications whenever data changes in your organization. Each webhook delivers a signed POST request to a URL you control, allowing external systems, automations, and integrations to react instantly to changes in Beebole. You can configure multiple webhooks, each with its own URL, name, secret, and event filter. Beebole signs every payload with HMAC-SHA256 so your endpoint can verify that requests are authentic.

​
Setting up a webhook

1

Open the webhook settings

Go to Settings > Integrations > Webhooks. Click Add webhook to create a new webhook subscription.
2

Configure the webhook

Fill in the following fields for your new webhook:
  • Name — A label to identify this webhook (for example, “Slack notifications” or “ERP sync”).
  • URL — The HTTPS endpoint that will receive POST requests from Beebole.
  • Secret — A secret key used to sign the payload. Beebole generates one automatically. You can regenerate it at any time by clicking Regenerate.
  • Enabled — Toggle whether this webhook is active.
  • Events — Choose All events to receive every event type, or select individual events from the list.
3

Configure the webhook

Fill in the following fields for your new webhook:
  • Name — A label to identify this webhook (for example, “Slack notifications” or “ERP sync”).
  • URL — The HTTPS endpoint that will receive POST requests from Beebole.
  • Secret — A secret key used to sign the payload. Beebole generates one automatically. You can regenerate it at any time by clicking Regenerate.
  • Enabled — Toggle whether this webhook is active.
  • Events — Choose All events to receive every event type, or select individual events from the list.
4

Save and test

Changes are saved automatically as you edit each field. Once the webhook is enabled and your endpoint is ready, trigger an event in Beebole (for example, update a project) and verify that your endpoint receives the request.
Use a service like webhook.site to inspect incoming payloads during development.

​
Payload format

Beebole sends a JSON POST request to your endpoint for each matching event. The payload structure is: 
{
  "event": "projectUpdate",
  "entityIds": ["64a1b2c3d4e5f6a7b8c9d0e1"],
  "deleteIds": [],
  "additionalInfo": null,
  "timestamp": 1712345678,
  "organisationId": "63f9a1b2c3d4e5f6a7b8c9d0"
}
FieldDescription
eventThe name of the event that triggered the webhook (see Available events).
entityIdsArray of entity IDs that were created or updated.
deleteIdsArray of entity IDs that were deleted.
additionalInfoOptional extra context provided by some events. null when not applicable.
timestampUnix timestamp (seconds) of when the event was emitted.
organisationIdThe Beebole organization ID that the event belongs to.

​
Available events

The following event names can be subscribed to individually or via All events:
EventTriggered when
absenceQuotaUpdateAn absence quota is created, updated, or deleted.
absenceTypeUpdateAn absence type is created, updated, or deleted.
approvalEventUpdateA timesheet approval action occurs.
billingUpdateA billing rate is created, updated, or deleted.
budgetUpdateA budget is created, updated, or deleted.
categoryUpdateA category is created, updated, or deleted.
customFieldUpdateA custom field definition is created, updated, or deleted.
customFieldValueUpdateA custom field value is created, updated, or deleted.
expenseRecordUpdateAn expense record is created, updated, or deleted.
expenseTypeUpdateAn expense type is created, updated, or deleted.
organisationUpdateOrganization settings are changed.
personUpdateA person is created, updated, or deleted.
planningUpdateA planning record is created, updated, or deleted.
projectCategoryUpdateA project category is created, updated, or deleted.
projectUpdateA project or subproject is created, updated, or deleted.
roleUpdateA role is created, updated, or deleted.
scheduleTypeUpdateA schedule type is created, updated, or deleted.
tagCategoryUpdateA tag category is created, updated, or deleted.
tagUpdateA tag is created, updated, or deleted.
taskCategoryUpdateA task category is created, updated, or deleted.
taskSettingsUpdateTask settings are changed.
taskUpdateA task is created, updated, or deleted.
timeRecordUpdateA time record is created, updated, or deleted.

​
Verifying the signature

Every request from Beebole includes an X-Beebole-Signature header containing a hex-encoded HMAC-SHA256 signature of the raw request body, prefixed with sha256=. Use your webhook’s Secret to verify this signature before processing the payload. Example verification in Node.js: 
const crypto = require('crypto')

function verifySignature(secret, rawBody, signatureHeader) {
  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(rawBody)
    .digest('hex')
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signatureHeader)
  )
}
Always verify the signature before acting on a webhook payload. Reject any request where the signature does not match.
The request also includes an X-Beebole-Event header containing the event name, which is identical to the event field in the JSON body.

​
Retry behavior

If your endpoint returns a non-2xx HTTP status code, or if the connection times out (requests time out after 10 seconds), Beebole automatically retries delivery with the following delays:
AttemptDelay
1st retry5 seconds
2nd retry10 seconds
3rd retry15 seconds
4th retry25 seconds
5th retry40 seconds
After 5 failed attempts, Beebole stops retrying and abandons the delivery. There is no user-visible delivery log in Beebole — failures are recorded only in Beebole’s internal server logs. Make sure your endpoint responds within 10 seconds — offload any slow processing to a background queue and return a 200 OK immediately.

​
Managing webhooks

  • To edit a webhook, click to expand its card in the list and update the fields. Changes save automatically.
  • To disable a webhook temporarily without deleting it, toggle the Enabled switch off.
  • To regenerate the secret (for example, if it has been compromised), click Regenerate in the Secret field. Update your endpoint with the new secret before re-enabling the webhook.
  • To delete a webhook, click Remove from the webhook card.

​
Related content

Custom integrations

Build custom integrations using the Beebole GraphQL API.

API introduction

Explore the full Beebole GraphQL API reference and schema.

All integrations

Explore all available Beebole integrations.

​
Frequently asked questions

Yes. You can create multiple webhook subscriptions pointing to the same URL, for example to separate event subscriptions with different secrets or names. Each webhook is independent.
Beebole sends all webhook payloads as HTTP POST requests with a Content-Type: application/json header.
The entityIds array in the payload contains the IDs of entities that were created or updated. The deleteIds array contains the IDs of entities that were deleted. Use these IDs to query the Beebole API for the current state of the affected records.
Beebole retries failed deliveries up to 5 times over approximately 95 seconds. If all retries fail, the delivery is abandoned. Events are not queued indefinitely. To avoid missing events during downtime, ensure your endpoint is highly available or implement a polling strategy with the Beebole API as a fallback.
Yes. Events triggered by any source — including integrations, the Beebole web app, and the API — will fire webhooks if a matching subscription is active. For example, a projectUpdate event fires whether a project is renamed directly in Beebole or via a Monday.com sync.