Webhooks

Set up webhooks to receive real-time notifications when transfer events occur on StrongholdNET.

Webhooks allow your application to be notified automatically when important events happen — such as a transfer being completed, failed, or updated — without having to poll the API.

---

Prerequisites

• A StrongholdNET account with access to the Developer Console
• A publicly accessible HTTPS endpoint to receive webhook events

---

Creating a Webhook

Step 1: Navigate to Webhooks

Log in to the Developer Console and select Webhooks from the sidebar navigation.

Step 2: Add a new webhook

Click the Add Webhook button to open the webhook creation form.

Step 3: Configure your webhook

Fill in the following fields:

Step 4: Select event types

Choose which events should trigger a notification. Each event type includes a payload example you can expand to preview the data structure your endpoint will receive.

Step 5: Create the webhook

Click Create webhook. On success, you'll be redirected to the webhooks list where your new webhook will appear as active.

Note: The first time you create a webhook for your organization, StrongholdNET automatically provisions webhook capabilities for your account. This is a one-time setup that happens transparently.

---

Managing Webhooks

Viewing your webhooks

The Webhooks tab displays all your registered webhooks as cards showing:

• Webhook name and endpoint URL
• Subscribed event types
• Active/inactive status

Editing a webhook

Click the Edit button on any webhook card to modify:

• Endpoint URL
• Webhook name
• Subscribed event types
• Custom headers
• Active/inactive status

Activating and deactivating

You can toggle a webhook's active state directly from the list or from the edit page:

• Active — The webhook receives event deliveries normally
• Inactive — Deliveries are paused; no events are sent to the endpoint

Webhooks cannot be deleted. To stop receiving events, deactivate the webhook.

---

Signing Secret

Every organization has a signing secret used to verify that incoming webhook deliveries are authentic and haven't been tampered with.

Viewing your signing secret

Navigate to the Signing secret tab on the Webhooks page to view and copy your secret.

Verifying webhook signatures

Each webhook delivery includes a signature header. To verify a delivery:

1. Extract the signature from the request headers
2. Compute an HMAC-SHA256 hash of the raw request body using your signing secret
3. Compare the computed hash with the received signature

Regenerating the signing secret

If your signing secret is compromised, click Regenerate on the Signing secret tab. This immediately invalidates the old secret — make sure to update your endpoint's verification logic with the new secret.

Warning: Regenerating the signing secret affects all webhooks in your organization. Update your endpoint verification code before or immediately after regenerating.

---

Webhook Delivery Logs

The Logs tab provides visibility into every webhook delivery attempt.

Viewing logs

The delivery log shows:

• Event type
• Delivery status (success or failed)
• Timestamp
• Response details

Filtering logs

Use the available filters to narrow down deliveries:

• Status — Filter by successful or failed deliveries
• Event type — Filter by specific event types
• Date range — Filter by time period

---

Best Practices

Endpoint design

• Respond quickly — Return a 2xx status code within the timeout window (30 seconds). Process the event asynchronously if needed.
• Use HTTPS — Always use HTTPS endpoints to protect webhook payloads in transit.
• Handle duplicates — Design your endpoint to be idempotent. The same event may be delivered more than once in rare cases.

Reliability

• Verify signatures — Always validate the webhook signature using your signing secret to ensure the delivery is authentic.
• Monitor delivery logs — Regularly check the Logs tab for failed deliveries and investigate any issues.
• Use custom headers — Add an authorization header to your webhook for an additional layer of endpoint security.

Error handling

• Automatic retries — Failed deliveries are automatically retried. Ensure your endpoint handles retries gracefully.
• Deactivate unused webhooks — If you no longer need notifications, deactivate the webhook rather than leaving a broken endpoint active.