Webhooks

NetOrca supports webhooks for Services. When a declaration is submitted and a Change Instance is created for a Service, or during the Change Instance process—for example, if the state of a Change Instance is updated by the Service Owner, NetOrca sends a webhook request to a specified target URL. A common use case for webhooks is triggering an external process such as executing an Ansible playbook.

Create a Webhook

In order to define a webhook for a Service, a POST request must be sent to /v1/external/serviceowner/webhooks/ endpoint with the following body:

HTTP requestPython SDKGUI

POST /v1/external/serviceowner/webhooks/ HTTP/1.1
Content-Type: application/json
Authorization: Token <YOUR_TOKEN>
{
    "name": "sample name",
    "description": "sample description",
    "service": <service_id defined in NetOrca>,
    "target_url": "<target_url>",
    "authorization": "<auth header, e.g. 'Bearer AwesomeKey'>",
    "change_instance_state": <Change Instance's state, e.g. PENDING> or null,
    "trigger_wait_time": <number of seconds> (*),
    "trigger_cooling_time": <number of seconds> (**)
}

from netorca_sdk import NetOrca

netorca = Netorca(fqdn=<YOUR_NETORCA_BASE_URL>, api_key=<YOUR_NETORCA_API_KEY>)
data = {
    "name": "sample name",
    "description": "sample description",
    "service": <service_id defined in NetOrca>,
    "target_url": "<target_url>",
    "authorization": "<auth header, e.g. 'Bearer AwesomeKey'>"
}
webhook = netorca.create_webhook(data=data)

Trigger a Webhook

There are 3 ways to trigger a webhook if it is enabled for a Service.

1. Trigger manually

   HTTP requestPython SDKGUI

   POST /v1/external/serviceowner/webhooks/<webhook_id>/trigger/ HTTP/1.1
   Content-Type: application/json
   Authorization: Token <YOUR_TOKEN>
   

   from netorca_sdk import NetOrca
   
   netorca = Netorca(fqdn=<YOUR_NETORCA_BASE_URL>, api_key=<YOUR_NETORCA_API_KEY>)
   webhook = netorca.webhook_trigger(webhook_id=<webhook_id>)
   

   

2. Trigger during the Change Instance process

   A webhook can also be triggered when a Change Instance reaches a specific state, as specified in the webhook’s change_instance_state field. If this field is set, the webhook will automatically fire once the Change Instance transitions to the designated state.

3. Trigger at Submission

   If the webhook’s change_instance_state field is set to null, it will be triggered immediately when a Consumer submits a declaration and a Change Instance is created for the associated Service.

When a webhook is triggered, an HTTP POST request is sent to the target URL, containing key details about the Service, including:

POST <webhook.target_url> HTTP/1.1
Content-Type: application/json
Authorization: <webhook.authorization>
{
  "id": <service_id>,
  "name": "<service_name>",
  "owner": {
    "id": <owner_id>,
    "name": "<service_owner_name>"
  },
  "state":  ""
}

Webhook Responses

When a webhook is triggered, NetOrca creates a corresponding response object in its database. This object records the HTTP status code and response body returned by the webhook’s target URL. Since webhook triggers are handled asynchronously, the response data may not be immediately available. To manage this, each response object includes a state that reflects the current progress of the HTTP request.

The possible state values are:

State	Description
OK	The Webhook HTTP request was sent and responded successfully.
FAILED	The Webhook HTTP request was sent, but the response was corrupted or timed out.
WAITING_FOR_RESPONSE	The Webhook HTTP request was sent and is awaiting a response.
SCHEDULED	The Webhook HTTP request is queued and waiting to be sent.

To see the list of Webhook Responses:

HTTP requestPython SDKGUI

GET /v1/external/serviceowner/webhook_responses/ HTTP/1.1
Content-Type: application/json
Authorization: Token <YOUR_TOKEN>

``````

HTTP requests Limitations

• (*) Service Owners can set a trigger_wait_time value to prevent the webhook from being triggered multiple times in quick succession. This is useful when multiple submissions occur close together—such as merging several merge requests back-to-back or approving many Change Instances at once—as it helps avoid excessive load by batching and buffering events, triggering the webhook just once.
• (**) Service Owners can also set a trigger_cooling_time value to ensures that the webhook is not triggered again immediately after it has already been triggered. By setting a trigger_cooling_time, redundant triggers within a short time frame are prevented, helping reduce load and unnecessary requests.
• In addition to the fields above, NetOrca Administrators can configure rate limits to control how many times a webhook can be triggered per minute. This helps prevent overload on external systems and ensures fair usage across multiple services.
• NetOrca Administrators can also set a limit on the number of webhook responses retained in NetOrca. For instance, if the limit is set to 10, only the 10 most recent responses will be stored—older entries will be automatically removed to maintain this cap.