Skip to main content

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 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. 
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:
KeyValue
AuthorizationBearer {{your_secret_token}}

​
Event Subscriptions

Select the events you want to receive. Events are grouped by category:
CategoryEvents
TransactionsApproved, Declined
SubscriptionsCreated, Suspended, Cancelled
CustomersCreated
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: 
{
  "event": "<category>",
  "action": "<action>",
  "data": { ... }
}
FieldDescription
eventEvent category (transaction, subscription, customer)
actionSpecific action that occurred (approved, declined, created, etc.)
dataEvent-specific payload

​
Transaction Approved

{
  "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

{
  "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.