> ## Documentation Index
> Fetch the complete documentation index at: https://docs.contactsmanager.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks Overview

> Introduction to ContactManager webhooks, explaining how they work, how to set them up, and best practices for implementation

# Webhooks Overview

Webhooks allow your application to receive real-time updates from ContactManager when specific events occur. Instead of polling our API for changes, webhooks deliver information to your server as events happen.

## How Webhooks Work

1. You register a webhook URL in your ContactManager dashboard
2. When an event occurs (like a user follows another user), ContactManager sends an HTTP POST request to your URL
3. Your server processes the event data and responds appropriately

## Getting Started with Webhooks

### Step 1: Set Up Your Webhook Endpoint

Create an endpoint on your server that can receive POST requests. This endpoint will receive webhook payloads containing event data.

### Step 2: Register Your Webhook

1. Go to [https://dash.contactsmanager.io/webhooks](https://dash.contactsmanager.io/webhooks)
2. Click "Add Webhook"
3. Enter your endpoint URL
4. Select which events you want to receive
5. Save your webhook configuration

### Step 3: Generate a Webhook Secret

For security, ContactManager signs all webhook requests with a secret key. You'll verify this signature to ensure requests are legitimate.

1. On the webhook configuration page, generate a new webhook secret
2. Store this secret securely in your application environment
3. Use this secret to verify incoming webhook payloads

### Step 4: Handle Webhook Events

When your endpoint receives a webhook request, you'll need to:

1. Verify the request signature using your webhook secret
2. Process the event based on its type
3. Return a 2xx response promptly (we recommend 200 OK)

## SDK Integration

For easier implementation, our SDKs include built-in webhook verification:

* [Python SDK](https://github.com/contactsmanager-io/contactsmanager-python)
* [Node.js SDK](https://github.com/contactsmanager-io/contactsmanager-node)

## Retry Logic

ContactManager implements automatic retry logic for webhook deliveries:

* If your endpoint returns a non-2xx response or times out, we'll retry the webhook
* Retries follow an exponential backoff schedule:
  * First retry: 3 seconds after the initial attempt
  * Second retry: 7 seconds after the first retry
* We make a maximum of 3 attempts (initial attempt + 2 retries)
* Each delivery attempt is logged with its status for debugging

This retry mechanism ensures reliable delivery even if your endpoint experiences temporary issues.

## Security Best Practices

* Always verify webhook signatures
* Process webhooks asynchronously
* Use HTTPS for your webhook endpoint
* Implement retry logic for failed webhook processing
* Store raw webhook payloads for debugging

## Next Steps

* [Explore available webhook events](/webhooks/events)
* [View webhook payload examples](/webhooks/payloads)
* [Learn about webhook signature verification](/webhooks/security)