Skip to content

Webhooks

NetOrca provides Webhook support for Services. When a declaration is submitted and a Change Instance is generated for the Service, a webhook request is sent to a specified target URL. For example, one application of this feature is to trigger the execution of 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:

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'>"
}

Trigger a Webhook

If a webhook is enabled for a Service, as soon as a Consumer submits a declaration, and one or more Change Instances are generated from that Service, the webhook will be triggered.

It is, also possible to trigger a webhook manually by

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

When the webhook is triggered, a POST HTTP request is sent to the target url with some of the essential Service's values are:

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 Response

When a webhook is triggered, a webhook response object is created in NetOrca's database. This object includes the status code and the response body from the triggered webhook's HTTP request. The webhook trigger operates asynchronously, so the response object might not immediately contain the final response. Therefore, each webhook response object includes a state to track the current status of the webhook HTTP request.

Here are the possible states for a Webhook Response:

  • OK: The Webhook HTTP request is sent and responded successfully
  • FAILED: The Webhook HTTP request is sent but the response was corrupted or timed out
  • WAITING_FOR_RESPONSE: The Webhook HTTP request is sent and waiting for its response
  • SCHEDULED: The Webhook HTTP request is waiting to be sent

HTTP requests limits

  • NetOrca admin can limit the number of triggers for each webhook per minute
  • They also can limit the number responses saved in NetOrca. For example, if they limit it to 10, only the 10 recent responses are available in NetOrca, the older responses will be deleted