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

# Integrate ErynoaGroup with your stack

> Connect ErynoaGroup to your existing stack using direct REST API calls, real-time webhook events, and best practices for error handling and retries.

ErynoaGroup is designed to fit into your existing workflows. This guide covers the main integration patterns: using the REST API directly, receiving real-time events via webhooks, and integrating with popular third-party tools.

## REST API integration

The most straightforward integration is calling the ErynoaGroup REST API directly from your backend. All endpoints accept JSON and return JSON.

**Example: Create a resource**

```bash theme={null}
curl -X POST https://api.erynoa.group/v1/resources \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Integration Resource",
    "type": "standard",
    "metadata": {
      "source": "my-app",
      "environment": "production"
    }
  }'
```

**Response:**

```json theme={null}
{
  "data": {
    "id": "res_01HX4K9Z2QBZJMFR5T6VWYP8D",
    "type": "resource",
    "status": "active",
    "name": "My Integration Resource",
    "created_at": "2024-01-15T10:30:00Z"
  }
}
```

## Webhook integration

Use webhooks to receive real-time notifications when events occur in ErynoaGroup, instead of polling the API.

<Steps>
  <Step title="Create a webhook endpoint">
    In your application, set up an HTTP endpoint that accepts POST requests. This endpoint must be publicly accessible and respond with `200 OK` within 10 seconds.
  </Step>

  <Step title="Register the endpoint in ErynoaGroup">
    In your dashboard, go to **Webhooks → Create Webhook**. Enter your endpoint URL and select the events you want to receive (e.g., `resource.created`, `resource.updated`, `resource.deleted`).
  </Step>

  <Step title="Verify webhook signatures">
    ErynoaGroup signs every webhook payload with your webhook secret using HMAC-SHA256. Verify the signature before processing the event:

    ```python theme={null}
    import hmac
    import hashlib

    def verify_webhook(payload_body: bytes, signature_header: str, secret: str) -> bool:
        expected = hmac.new(
            secret.encode(),
            payload_body,
            hashlib.sha256
        ).hexdigest()
        return hmac.compare_digest(expected, signature_header)
    ```

    The signature is sent in the `X-Erynoa-Signature` header.
  </Step>

  <Step title="Handle the event">
    Parse the JSON payload and process the event. Return `200 OK` immediately and handle any slow processing asynchronously.

    ```python theme={null}
    from flask import Flask, request, jsonify

    app = Flask(__name__)

    @app.route("/webhook", methods=["POST"])
    def handle_webhook():
        payload = request.get_json()
        event_type = payload["event"]["type"]

        # Process asynchronously
        if event_type == "resource.created":
            queue.enqueue(process_resource_created, payload)

        return jsonify({"received": True}), 200
    ```
  </Step>
</Steps>

## Error handling best practices

<CardGroup cols={2}>
  <Card title="Retry with backoff" icon="rotate-right">
    On `5xx` errors or network timeouts, retry with exponential backoff: wait 1s, then 2s, then 4s, up to 3 retries.
  </Card>

  <Card title="Idempotency keys" icon="fingerprint">
    Include an `Idempotency-Key` header on `POST` requests to safely retry without creating duplicate resources.
  </Card>

  <Card title="Log request IDs" icon="list">
    Every response includes a `X-Request-ID` header. Log this value to correlate your logs with ErynoaGroup support if needed.
  </Card>

  <Card title="Graceful degradation" icon="shield">
    Design your application to function (in a degraded mode) when ErynoaGroup is temporarily unavailable.
  </Card>
</CardGroup>