Webhook configuration

You can efficiently manage and safeguard the communication between Namirial Onboarding and your systems, guaranteeing that all webhook notifications are delivered reliably and securely. Below is an example payload for a webhook notification presented in JSON format.

Example webhook payload in JSON

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "type": "STATUS_UPDATE",
  "createdAt": "2024-10-29T17:42:16Z",
  "request": {
    "requestId": "123e4567-e89b-12d3-a456-426614174001",
    "requestTypeId": "123e4567-e89b-12d3-a456-426614174002",
    "status": "COMPLETED"
  }
}

The provided JSON payload represents a notification object that is used to inform about updates related to an onboarding request. Here is a detailed breakdown of each component:

id: This is a unique identifier for the notification, formatted as a UUIDv4. It ensures that each notification can be distinctly identified.
- Example: "123e4567-e89b-12d3-a456-426614174000"
type: This field indicates the type of update that triggered the notification. Currently, the example value is "STATUS_UPDATE", but additional values may be added over time to represent different types of updates.
- Example: "STATUS_UPDATE"
createdAt: This timestamp indicates when the notification was created. It follows the ISO 8601 format for date and time.
- Example: "2024-10-29T17:42:16Z"
request: This nested object contains details about the specific onboarding request that the notification pertains to.
- requestId: A unique identifier for the onboarding request, formatted as a UUIDv4.
  - Example: "123e4567-e89b-12d3-a456-426614174001"
- requestTypeId: This field references the type of the request, also formatted as a UUIDv4. The actual value would depend on the preset workflow in the system.
  - Example: "123e4567-e89b-12d3-a456-426614174002"
- status: This field indicates the current status of the request. Possible values include statuses like "CREATED", "RUNNING", "COMPLETED", etc.
  - Example: "COMPLETED"

Webhook settings

Each request type can be linked to a specific webhook configuration, ensuring that notifications for that workflow are directed to the designated endpoint, which necessitates particular authentication.

The webhook settings include the following parameters.

Destination URL Configuration

This API call allows you to set the destination URL where the webhook notifications will be sent.

Authentication Methods

Client-Based Authentication: This method involves using client credentials to authenticate requests to the webhook URL. It ensures that only authorized clients can receive the webhook notifications.
HTTP Header-Based Authentication: This method supports various authentication schemes that utilize HTTP headers. You can configure headers such as Authorization, API-Key, or any custom headers required by your security protocols. This flexibility allows you to integrate the webhook notifications securely into your existing infrastructure.

By using these API calls, you can effectively manage and secure the communication between Namirial Onboarding and your systems, ensuring that all webhook notifications are delivered reliably and securely.

Create request type webhooks setting

This API call allows you to create a webhook configuration for a specific request type. The webhook configuration includes the destination URL and the authentication method required for the webhook notifications.

Endpoint

URL: /requestType/{id}/webhookConfigurations
Method: POST

Headers

Ensure you include the following headers in your request:

Accept: application/json
Content-Type: application/json
X-Api-Key: YOUR_API_KEY (replace YOUR_API_KEY with your actual API key)

Parameters

id: The unique identifier for the request type.

Example Request Body

{
  "url": "https://your.domain/webhook",
  "authentication": {
    "headers": {
      "Authorization": "Bearer your-token",
      "API-Key": "your-api-key",
      "additionalProp3": "string"
    },
    "client_key": "-----BEGIN RSA PRIVATE KEY-----\nMIIH/TCCBeWgAwIBAgIQaBYE3/M08XHYCnNVmcFBcjANBgkqhkiG9w0BAQsFADBy\n...",
    "client_cert": "-----BEGIN CERTIFICATE-----\nMIIH/TCCBeWgAwIBAgIQaBYE3/M08XHYCnNVmcFBcjANBgkqhkiG9w0BAQsFADBy\n..."
  }
}

Responses

200 OK

Description: The webhook settings created.

Example Response:

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "url": "https://your.domain/webhook",
  "createdAt": "2024-10-22T12:19:12.269594Z"
}

400 Bad Request

Description: Bad Request described following Problem Details (RFC 9457).

Example Response:

{
  "type": "about:blank",
  "status": 400,
  "title": "Request validation error",
  "detail": "The has a malformed body property.",
  "instance": "urn:uuid:123e4567-e89b-12d3-a456-426614174000?ts=1729667463",
  "retryable": false,
  "errors": [
    {
      "detail": "Property 'dummyField' is not defined in the schema and the schema does not allow additional properties.",
      "pointer": "/parameters/dummyField",
      "field": "dummyField",
      "reason": "additionalProperties"
    }
  ]
}

Get request type webhooks setting

This API call allows you to retrieve the webhook configurations associated with a specific request type. These configurations include details such as the destination URL and the creation timestamp.

Endpoint

URL: /requestType/{id}/webhookConfigurations
Method: GET

Headers

Ensure you include the following headers in your request:

Accept: application/json
Content-Type: application/json
X-Api-Key: YOUR_API_KEY (replace YOUR_API_KEY with your actual API key)

Parameters

id: The unique identifier for the request type, formatted as a UUID.

Responses

200 OK

Description: The webhook configurations for the specified request type.

Example Response:

{
  "content": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "url": "https://your.domain/webhook",
      "createdAt": "2024-10-22T12:19:12.269594Z"
    }
  ]
}

400 Bad Request

Description: Bad Request described following Problem Details (RFC 9457).

Example Response:

{
  "type": "about:blank",
  "status": 400,
  "title": "Request validation error",
  "detail": "The has a malformed body property.",
  "instance": "urn:uuid:123e4567-e89b-12d3-a456-426614174000?ts=1729667463",
  "retryable": false,
  "errors": [
    {
      "detail": "Property 'dummyField' is not defined in the schema and the schema does not allow additional properties.",
      "pointer": "/parameters/dummyField",
      "field": "dummyField",
      "reason": "additionalProperties"
    }
  ]
}

Delete request type webhooks setting

This API call allows you to delete a specific webhook configuration associated with a request type.

Endpoint

URL: /requestType/{id}/webhookConfigurations/{webhookConfigurationId}
Method: DELETE

Headers

Ensure you include the following headers in your request:

Accept: application/json
Content-Type: application/json
X-Api-Key: YOUR_API_KEY (replace YOUR_API_KEY with your actual API key)

Parameters

id: The unique identifier for the request type.
webhookConfigurationId: The unique identifier for the webhook configuration, formatted as a UUID.

Responses

204 No Content
- Description: The resource was deleted successfully.

400 Bad Request

Description: Bad Request described following Problem Details (RFC 9457).

Example Response:

{
  "type": "about:blank",
  "status": 400,
  "title": "Request validation error",
  "detail": "The has a malformed body property.",
  "instance": "urn:uuid:123e4567-e89b-12d3-a456-426614174000?ts=1729667463",
  "retryable": false,
  "errors": [
    {
      "detail": "Property 'dummyField' is not defined in the schema and the schema does not allow additional properties.",
      "pointer": "/parameters/dummyField",
      "field": "dummyField",
      "reason": "additionalProperties"
    }
  ]
}