Create Webhook Key

Step-by-Step Guide to Creating Webhooks in Niural

Step 1: Navigate to Webhooks

From the Niural Dashboard, go to the Organization section in the appbar.
In the sidebar under the Developer section, select Webhooks.

Step 2: Create New Webhook

Click the Add New Webhook button located at the top right of the screen to start creating a new webhook.

Step 3: Fill in Webhook Details
A panel titled Create Webhook will open. Here, you will enter the following details:

Webhook Name: Provide a descriptive name for your webhook, such as “Pay on Demand” or “Contract Status Update,” to easily identify it later.
Description (optional): Add a brief explanation of the webhook's purpose to help with organization and future reference.
Metadata (optional): If you need to include additional data with each event, define it in JSON format here. For example:
```
{
  "client_id": "4q389dfhjslkfjaslkdfjalskf",
  "additional_info": "Sample metadata"
}
```
In the Endpoint URL field, enter the URL where you want to receive the webhook events
Under Events, specify the type of events you want to receive. Niural currently supports All Events.

Step 4 : Review Signing Secret

Once the webhook is created, you’ll see a confirmation message with a Signing Secret. Copy this secret and store it securely, as it’s required to verify the authenticity of incoming requests from Niural.

How to Rotating the Webhook Signing Secret

Step 1: Open Webhook Details:

In the Webhooks section, select the webhook for which you want to rotate the signing secret.
This will open the Webhook Details panel on the right, showing the current signing secret and other webhook configurations.

Step 2: Rotate Secret:

Click on the Rotate Secret button within the details panel.
A prompt will appear, asking if you’re sure you want to rotate the signing secret. This action will expire the old secret, which will remain valid for 24 hours, allowing time to update your endpoint.

Step 3: Confirm Rotation:

Click Rotate to confirm. Niural will generate a new signing secret, which will appear on the screen.
Copy the New Secret: This secret will not be shown again after you leave the screen, so make sure to copy and securely store it for future validation.

Step 4: Update Endpoint with New Secret:

Ensure that your server is updated to use the new signing secret. This is essential for authenticating incoming requests after the old secret expires.

Step 5: Complete Rotation:

Click Done to finish. Your webhook will now use the new signing secret for verification.

Editing a Webhook

Step 1: Navigate to Webhooks:
From your Niural dashboard, go to Organization in the sidebar and select Webhooks under the Developer section.

Step 2: Find the Webhook to Edit:
In the list of webhooks, locate the webhook you want to modify.

Click on Edit next to the webhook name. This will open the webhook details panel, where you can make changes to the configuration.

Step 3: Edit Webhook Details:

In the details panel, you can update the Webhook Name, Description, Endpoint URL, Metadata, and the Event types you want the webhook to listen for. Make the necessary changes and confirm each modification.

Step 4: Save Changes

After editing, ensure you save the changes. Niural may require you to confirm or test the new configurations.

Managing Webhook Subscriptions

You can update or delete existing webhook subscriptions through the Niural platform under the Webhooks tab. Additionally, you can disable a webhook if needed. Niural does not attempt to deliver notifications for events that occur while the webhook is disabled. Alternatively, you can manage webhook subscriptions programmatically using the Niural API.

Handling Webhook Events

Once an endpoint is registered, Niural sends an HTTP POST request to the URL every time an event occurs. The HTTP POST request will contain JSON data relevant to the event that triggered it.

Verifying the Webhook

Before processing a webhook, you can verify that it came from Niural by checking the digital signature.
Each webhook request includes an x-niural-signature header, which is generated using your webhook's signing key and the request data. Verifying the signature ensures that the request is legitimate. You can learn more about verifying webhook signatures here.

Responding to the Webhook

Once your system receives the webhook, it should respond with a 200 OK status to acknowledge that the data has been received. Any response outside the 2XX range will indicate that the webhook was not properly received, and Niural will consider the delivery to have failed.

Note that Niural does not follow redirects, and 3XX HTTP responses will be treated as errors.