Webhooks

Webhooks let Ecrypt push real-time event notifications to your own systems. Whenever a configured event happens — a card transaction is approved, a subscription is cancelled, a new customer is created — Ecrypt sends an HTTPS POST request to a URL you control, with the event details in the body. You can then use those notifications to update your database, send your own emails, fire downstream automations, or sync state with other tools. This guide covers the Webhook Management page where you create, edit, and delete webhook endpoints, including the events you can subscribe to and the custom headers you can attach to outgoing requests.

---

​

Navigation

From the left sidebar: Settings → Developer Tools → Webhook Management The page is split into two sections stacked vertically:

1. Create Webhook — the form at the top where you configure a new webhook.
2. Webhook’s Table — the list of webhooks you’ve already created.

---

​

Create Webhook

The form at the top of the page is used to register a new webhook endpoint.

​

Webhook Info

​

Event Selection

Checkboxes grouped into three categories. Tick the events you want this webhook to receive — leaving a category unchecked means Ecrypt won’t fire for that event. A single webhook can subscribe to any combination of events from any number of groups.

​

Custom Headers

Optional HTTP headers Ecrypt will attach to every outgoing webhook request to this URL. Useful for authentication (e.g., a shared secret in Authorization), routing, or anything else your endpoint needs to validate the request.

​

Save

Click GENERATE WEBHOOK to register the endpoint. It will appear in the Webhook’s Table below.

---

​

Webhook’s Table

A list of every webhook you’ve registered. Pagination controls (rows per page, page arrows) appear at the bottom right.

​

Edit a Webhook

Clicking Edit scrolls the top form into “Edit” mode. The heading changes to “Edit [URL]” and the form is pre-populated with the webhook’s current settings:

• Webhook URL is read-only (greyed out) — you cannot change the destination once created. Delete and re-create with a new URL if you need to move endpoints.
• Event checkboxes are pre-checked according to the webhook’s current subscription. Toggle as needed.
• Custom Headers can be added or removed.

Buttons: SAVE WEBHOOK to apply changes, CANCEL to discard them.

​

Delete a Webhook

Clicking the red Delete opens a confirmation dialog:

Are you sure you want to delete this webhook?

Buttons: DELETE / CANCEL. Deletion is immediate. Ecrypt will stop sending events to the URL the moment you confirm.

---

​

How Webhooks Work

When a subscribed event happens on your account, Ecrypt makes an HTTPS POST request to the Webhook URL with the event payload in the body. If you’ve configured Custom Headers, they’re attached to every request. Your endpoint should:

1. Respond with a 2xx status code as quickly as possible to acknowledge receipt.
2. Verify the request is authentic (typically via a shared secret in a custom header).
3. Process the event asynchronously after acknowledging — don’t do heavy work inside the request itself.

Failures to deliver (non-2xx responses, timeouts, network errors) are handled by Ecrypt’s delivery system; your endpoint should be designed to handle the same event arriving more than once (idempotency).

---

​

Tips & Best Practices

Always use HTTPS for your webhook URL — the form requires it, and for good reason. Webhook payloads can include transaction amounts, customer identifiers, and subscription state, which should not transit the public internet in cleartext. Treat webhooks as untrusted input on your endpoint. Anyone who can hit your URL could try to forge an event, so use a Custom Header with a strong shared secret (or a signed token) and verify it on every incoming request before acting on the payload. Reject requests that don’t match. Subscribe only to the events you actually need. A webhook subscribed to every event will receive many more requests than one focused on, say, just “Transactions → Approved” — and every extra request is one more thing your endpoint has to acknowledge. If you only care about successful sales, leave Declined unchecked; if you only care about cancellations, skip Created and Suspended. Design your endpoint for at-least-once delivery. Webhooks can be retried, network blips can cause duplicates, and you should be able to handle the same event arriving twice without doing the work twice. A common pattern is to record the event’s transaction ID (or subscription ID, customer ID) the first time you process it and skip subsequent deliveries with the same ID. When you need to change your endpoint URL (e.g., moving from staging to production, or to a new domain), remember that you can’t edit the URL on an existing webhook — you’ll need to delete the old one and create a new one. Plan the cutover carefully so you don’t miss events during the swap, or run both endpoints in parallel for a brief window and de-duplicate on your side. Finally, the Status column will show ENABLED for healthy webhooks. If you see anything else, or if you suspect events aren’t being delivered, double-check the URL is reachable from the public internet, the TLS certificate is valid, and your endpoint is returning 2xx quickly enough that Ecrypt doesn’t time out.