Contact Group webhooks enable BoldDesk to automatically notify external applications whenever a contact group is created, updated, or deleted. This allows you to keep company, organization, or customer group information synchronized across external systems such as CRMs, directory services, provisioning platforms, and custom business applications.

This article focuses on configuring and using Contact Group webhooks for data synchronization. For information about creating webhooks, configuring authentication, validating signatures, activating webhook events, and handling delivery failures, refer to the related webhook articles listed at the end of this guide.

Supported Contact Group Webhook Events

The Contact Group module supports the following webhook events:

Use Cases

Use Contact Group webhooks to:

• Create a corresponding company or organization record in an external CRM.
• Synchronize Contact Group updates with an external directory.
• Start an account-provisioning workflow when a Contact Group is created.
• Update external records when Contact Group information changes.
• Archive, deactivate, or remove an external record when a Contact Group is deleted.
• Send Contact Group data to an internal reporting or data-processing system.

Prerequisites

Before configuring the webhook, ensure that:

• The receiving system provides a secure (HTTPS) endpoint that can accept webhook requests.
• The endpoint supports the required authentication method and can process the configured payload format.
• The receiving system can handle Contact Group create, update, and delete events.
• You have permission to Manage webhooks in BoldDesk.
• Any Contact Group fields required by the receiving system are available as webhook placeholders.

Create the Contact Group Webhook

1. Go to Admin → Webhooks.
2. Select Add Webhook.
3. Enter a descriptive webhook name.
4. Enter a description that explains the webhook’s purpose.
5. Select Contact Group as the module.
6. Select one or more of the following events:
   • Created
   • Updated
   • Deleted
7. Enter the destination endpoint under Webhook Endpoint.
8. Select the HTTP request method expected by the endpoint:
   • POST
   • PUT
   • PATCH
   • DELETE
9. Configure authentication, signing, custom headers, or conditions when required.
10. Configure the webhook payload.
11. Select Add to save the webhook.

Choose the Payload Type

BoldDesk supports the following webhook payload options:

Configure a Default Payload

Use Default Payload when the receiving system can process the standard Contact Group payload.

To configure it:

1. Open the webhook’s Payload section.
2. Select Default Payload.
3. Select the Contact Group fields that must be included.
4. Enable the option to include all fields only when the endpoint requires the complete Contact Group record.
5. Review the selected fields.
6. Save the webhook.

Configure an Advanced JSON Payload

Use Advanced Payload when the receiving endpoint requires a custom JSON structure.

To configure it:

1. Open the webhook’s Payload section.
2. Select Advanced Payload.
3. Select JSON as the content type.
4. Configure the custom body.
5. Use Insert Placeholders to add the required Contact Group fields.
6. Confirm that the body contains valid JSON.
7. Save the webhook.

Create the Advanced Payload Structure

Use the following as a structural example only. Replace each sample value with the exact placeholder shown under Insert Placeholders:

{
  "contactGroupName": "{{CONTACT_GROUP_NAME_PLACEHOLDER}}",
  "description": "{{CONTACT_GROUP_DESCRIPTION_PLACEHOLDER}}",
  "notes": "{{CONTACT_GROUP_NOTES_PLACEHOLDER}}"
}

If the Contact Group domain is available under Insert Placeholders, add it using the exact placeholder supplied by BoldDesk:

{
  "contactGroupName": "{{CONTACT_GROUP_NAME_PLACEHOLDER}}",
  "description": "{{CONTACT_GROUP_DESCRIPTION_PLACEHOLDER}}",
  "notes": "{{CONTACT_GROUP_NOTES_PLACEHOLDER}}",
  "domain": "{{CONTACT_GROUP_DOMAIN_PLACEHOLDER}}"
}

If the endpoint requires custom fields, insert the applicable custom-field placeholders through the BoldDesk interface.

Understand the Webhook Headers

BoldDesk sends system headers with the webhook request. Depending on the webhook configuration, the request may also include authentication, signing, and custom headers.

Common system headers include:

If one endpoint processes multiple Contact Group events, use the Event-Type header or another event value included in the payload to determine whether the receiving system should create, update, or delete a record.

Process Contact Group Events in the Receiving System

The receiving system should perform the appropriate action for each event.

The receiving system should store or map a stable identifier, such as the BoldDesk Contact Group ID, so that future update and delete events affect the correct external record.

Secure the Webhook

Configure security according to the destination endpoint’s requirements.

BoldDesk webhook configuration supports options such as:

• Authentication
• Request signing
• Custom headers
• Endpoint-specific credentials

Apply the following practices:

• Use an HTTPS endpoint.
• Validate signed requests according to BoldDesk webhook security guidance.
• Store API keys and secrets securely.
• Do not include passwords or private API keys directly in the JSON payload.
• Reject requests that fail authentication or signature verification.
• Limit the endpoint to the operations required for Contact Group synchronization.
• Record request identifiers, event types, and processing results for auditing.

For complete signature-verification instructions, learn more on How to Secure Webhooks in BoldDesk.

Troubleshoot Failed Webhook Requests

If the destination does not receive or process the webhook:

1. Go to Admin → Audit Logs → Webhook Failure Logs.
2. Locate the failed request.
3. Review:
   • Destination endpoint
   • HTTP request method
   • Status code
   • Error response
   • Event type
   • Failure time
4. Confirm that the endpoint is reachable.
5. Confirm that the endpoint accepts the configured HTTP method.
6. Validate the JSON payload.
7. Verify the authentication, signing, and custom headers.
8. Confirm that the destination system accepts the included fields.
9. Correct the issue and test the webhook again.

Common webhook failures include:

Frequently Asked Questions

1. Which Events Are Available for Contact Group Webhooks?
   The Contact Group module supports the following webhook events:

   • Created
   • Updated
   • Deleted

2. Does Contact Group Support a Permanently Deleted Event?
   No. The documented Contact Group deletion event is Deleted.
   The Permanently Deleted event applies to other supported modules, including Ticket and Contact.

3. What Is the Difference Between Default Payload and Advanced Payload?
   Default Payload uses the event-based BoldDesk payload structure and lets you select the required fields.
   Advanced Payload lets you define a custom payload structure for the destination endpoint.

4. Can One Webhook Handle All Contact Group Events?
   Yes. Select Created, Updated, and Deleted in one webhook when the same endpoint processes all three events.
   The receiving system should inspect the Event-Type header or an event value in the payload to determine which action to perform.

5. Can I Configure Separate Endpoints for Each Event?
   Yes. Create separate webhooks when different endpoints or HTTP methods must process the Created, Updated, and Deleted events.

6. Can I Add Authentication Headers?
   Yes. Configure authentication or custom headers according to the destination endpoint’s requirements.
   Do not copy example authorization values from the documentation into a production webhook.

7. How Can the Receiving System Verify the Request?
   Configure webhook signing and validate the request according to How to Secure Webhooks in BoldDesk.
   Avoid implementing signature validation based only on an example x-signature value.

8. What Happens When a Contact Group Is Updated?
   The Updated event runs when a field is changed in an existing Contact Group.
   The receiving system should process only the fields required by its synchronization logic.

9. Should the Receiving System Delete an External Record Immediately?
   The appropriate action depends on the external system’s retention requirements.
   For systems that require audit history, archive or deactivate the external record instead of permanently deleting it.

Related Articles

1. Webhook Payloads, Headers, and Event
2. How to Create and Manage Webhooks in BoldDesk Tickets
3. How to Secure Webhooks in BoldDesk
4. Webhook Failure Handling in BoldDesk