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

# Webhooks

Webhooks let ECRYPT notify your server in real time when events occur in your account. When a subscribed event fires, ECRYPT sends an HTTP `POST` request containing a JSON payload to the URL you configure.

***

## Register a Webhook

Webhooks are managed from the ECRYPT Dashboard.

1. Log in to the ECRYPT Dashboard.
2. Navigate to **Settings** > **Account Settings** > **Developer Tools**.
3. Under **Developer Tools**, locate the **Webhooks** section and click **Edit**.
4. Click **+ Webhook** in the top-right corner to open the **New Webhook** modal.

***

## Configure the Webhook

### Webhook URL

Enter the publicly accessible HTTPS endpoint on your server that will receive webhook events.

```text theme={null} theme={null}
https://www.yourdomain.com/webhooks
```

ECRYPT sends a `POST` request to this URL each time a subscribed event occurs.

### Headers

If your endpoint requires authentication or custom headers, click **+ Add** to attach key/value header pairs. These headers are included on every outbound request to your endpoint.

A common pattern is to pass a shared secret for request verification:

| Key             | Value                          |
| --------------- | ------------------------------ |
| `Authorization` | `Bearer {{your_secret_token}}` |

### Event Subscriptions

Select the events you want to receive. Events are grouped by category:

| Category          | Events                        |
| ----------------- | ----------------------------- |
| **Transactions**  | Approved, Declined            |
| **Subscriptions** | Created, Suspended, Cancelled |
| **Customers**     | Created                       |

You can subscribe to any combination of events on a single webhook endpoint, or create separate webhooks for different event groups.

### Enable / Disable

Use the **Disable/Enable** toggle to activate or deactivate a webhook without deleting it. Disabled webhooks do not receive event deliveries.

Click **Save Webhook** when finished.

***

## Webhook Payload

All webhook events share a common envelope:

```json theme={null} theme={null}
{
  "event": "<category>",
  "action": "<action>",
  "data": { ... }
}
```

| Field    | Description                                                             |
| -------- | ----------------------------------------------------------------------- |
| `event`  | Event category (`transaction`, `subscription`, `customer`)              |
| `action` | Specific action that occurred (`approved`, `declined`, `created`, etc.) |
| `data`   | Event-specific payload                                                  |

### Transaction Approved

```json theme={null} theme={null}
{
  "event": "transaction",
  "action": "approved",
  "data": {
    "Transaction": {
      "TransactionId": "258377101",
      "AuthCode": "123456",
      "ResponseCode": "APPROVED",
      "ResponseText": "Approved",
      "Latency": 2938,
      "Avs": {
        "Code": "",
        "Text": ""
      },
      "Cvv": {
        "Code": "N",
        "Text": "CVV2/CVC2 no match"
      },
      "Amount": 1.50,
      "Metadata": {
        "credit_card_network": "visa",
        "credit_card_number": "4xxxxxxxxxxx1111",
        "credit_card_expires": "0132",
        "order_tax": 0,
        "order_tip": 0
      },
      "RequestId": "0HN9PI9AU09HO00000004",
      "Errors": null
    },
    "ReferenceTransactionId": "",
    "Path": "/v1/transactions/sale"
  }
}
```

### Transaction Declined

```json theme={null} theme={null}
{
  "event": "transaction",
  "action": "declined",
  "data": {
    "Transaction": {
      "TransactionId": "258378101",
      "AuthCode": "",
      "ResponseCode": "DECLINED",
      "ResponseText": "Transaction Rejected",
      "Latency": 658,
      "Avs": {
        "Code": "",
        "Text": ""
      },
      "Cvv": {
        "Code": "",
        "Text": ""
      },
      "Amount": 1.50,
      "Metadata": {
        "credit_card_network": "visa",
        "credit_card_number": "4xxxxxxxxxxx1111",
        "credit_card_expires": "0132",
        "order_tax": 0,
        "order_tip": 0
      },
      "RequestId": "0HN9PI9ATUN5100000003",
      "Errors": null
    },
    "ReferenceTransactionId": "",
    "Path": "/v1/transactions/sale"
  }
}
```

***

## Best Practices

**Respond quickly.** Return an HTTP `200` status as soon as your endpoint receives the request. Perform any processing asynchronously to avoid timeouts.

**Verify the source.** Use a shared secret passed via a custom header to confirm requests are coming from ECRYPT. Reject any requests that fail this check.

**Handle duplicates.** Webhooks may be delivered more than once in rare cases. Use `RequestId` or `TransactionId` to deduplicate events on your end.

**Use HTTPS.** Your endpoint must be accessible over HTTPS. Plain HTTP endpoints are not supported.