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

# Webhooks

> Receive Network event notifications and handle webhook delivery, security, retries, and recovery

Webhooks allow you to receive real-time HTTP notifications when events occur in your Network. Instead of polling the API for changes, webhooks push data to your server as events happen.

## How It Works

1. You configure a webhook endpoint URL in your Network settings
2. You select which events you want to receive
3. When an event occurs, Mighty Networks sends an HTTP POST request to your URL
4. Your server processes the webhook and responds with any `2xx` status code (200, 201, 202, 204, etc.)

## Webhook Delivery Format

Webhooks are delivered as HTTP POST requests with JSON payloads:

```http theme={null}
POST /your-webhook-endpoint
Host: your-domain.com
Content-Type: application/json
Accept: application/json
Authorization: Bearer YOUR_CONFIGURED_API_KEY

{
  "event_id": "abc123-uuid",
  "event_timestamp": "2024-01-15T10:30:00Z",
  "event_type": "PostCreatedHook",
  "payload": {
    "id": 12345,
    "title": "Example post title",
    "author": {
      "id": 67890,
      "email": "user@example.com",
      "first_name": "John"
    },
    "space_id": 111,
    "created_at": "2024-01-15T10:30:00Z"
  }
}
```

## Available Events

Every event and its payload schema has its own page in the **Webhooks** group of this tab's sidebar, starting with [PostCreated](/api-reference/webhooks/postcreated).

## Security

* **HTTPS Required**: Webhook endpoints must use HTTPS in production
* **Authentication**: Configure an API key that will be included as a `Bearer` token in the `Authorization` header
* **Verify the source**: Always validate the `Authorization` header matches your configured key

## Best Practices

<AccordionGroup>
  <Accordion title="Respond quickly">
    Return any `2xx` status code (200, 201, 202, 204, etc.) as fast as possible. Process the webhook payload asynchronously if needed—webhooks time out after 10 seconds.
  </Accordion>

  <Accordion title="Handle retries">
    Webhooks are retried on failure with any non-2xx status code. Implement idempotency to handle duplicate deliveries gracefully.
  </Accordion>

  <Accordion title="Keep your endpoint healthy">
    Repeated failures trip a circuit breaker that temporarily pauses delivery to your endpoint. Monitor your endpoint's availability so deliveries aren't suspended. See [Circuit breaker](#circuit-breaker) for details.
  </Accordion>

  <Accordion title="Expect async delivery">
    Webhooks are delivered asynchronously via background jobs. There may be a slight delay between when an event occurs and when you receive the webhook.
  </Accordion>

  <Accordion title="Log webhook payloads">
    Store incoming webhook data for debugging and auditing purposes.
  </Accordion>
</AccordionGroup>

## Expected Responses

Your endpoint should return any `2xx` status code to acknowledge successful receipt. Common success codes include 200 (OK), 201 (Created), 202 (Accepted), and 204 (No Content):

| Status Code | Meaning |
| - | - |
| 2xx (200-299) | Webhook received successfully |
| Any non-2xx status | Delivery failed—will be retried |

## Circuit breaker

Outbound webhook delivery is protected by a [circuit breaker](https://martinfowler.com/bliki/CircuitBreaker.html). If your endpoint fails repeatedly in a row, we temporarily stop delivering webhooks to it rather than continuing to retry against an endpoint that appears to be down.

* **Trips on repeated failures**: When deliveries to your endpoint fail multiple consecutive times (any non-2xx response, a timeout, or a connection error), the circuit breaker opens and delivery is paused.
* **Delivery is paused temporarily**: While the circuit is open, new webhooks for that endpoint are not delivered. This protects both your service and ours from wasted retries against a failing endpoint.
* **Automatic recovery**: After a cooldown period, we probe your endpoint again. Once it responds successfully, the circuit closes and normal delivery resumes automatically—no manual intervention required.

<Tip>
  Keep your endpoint highly available and return a `2xx` status quickly to avoid tripping the circuit breaker. If you notice a gap in delivery, check your endpoint's logs and uptime for a recent run of failures.
</Tip>