Webhook APIs

You can manage webhooks with the following APIs.

Get a Webhook
Get Webhooks
Create a Webhook
Update a Webhook
Delete a Webhook

Permissions

There are two types of permissions for webhook endpoints and event. Webhook Admin and Webhook User.

Webhook Admin:

Used for users that should have access to all webhook endpoints within the organization.

Webhook User:

Used for external users or users meant to have access to specific webhook endpoints
For these users to have access they must first be given permissions as a Webhook User, then a request must be made to Ovation for that user to be added to specific webhook endpoints.

Get a Webhook

Use this API to get information about a specific webhook.

HTTP Request

GET /api/v3/project_templates/{projectTemplateId}/webhook_endpoints/{webhookId}

Query Parameters

Key	Required	Description
`projectTemplateId`	yes	Supply the internal identifier of the requisition template that the webhook applies to. (It's the 789 in this example: https://lab.ovation.io/orgs/123/projects/456/requisition-settings/789/template-information.)
`webhookId`	yes	Supply the internal identifier of the webhook. Retrieve this information by using the API to Get Webhooks.

Response Body

{
  "webhook_endpoint": {
    "id": 789,
    "target_url": "http://api.test.com/",
    "event": "report_signed",
    "username": "someUser",
    "project_requisition_template_association_id": 456,
    "requestHeaders": {
	"someKey": "any value",
	"anotherKey": "some other value",
	...
    }
  }
}

Field name	Description
`id`	The internal identifier of the webhook (the same value supplied in the URL as `webhookId`)
`target_url`	The URL called by the webhook
`event`	The event that triggers calling the URL
`username`	The username passed when calling the URL The password is retained and also passed, but not provided in this response body.
`project_requisition_template_association_id`	The internal identifier of the requisition template that the webhook applies to (the same value supplied in the URL as `projectTemplateId`)
`requestHeaders`	A list of header name/value pairs These are passed in the header when calling the URL. Their meaning is up to the interpretation of the receiving service.

Get Webhooks

Use this API to get information about all webhooks.

HTTP Request

GET /api/v3/project_templates/{projectTemplateId}/webhook_endpoints

Query Parameters

Key	Required	Description
`projectTemplateId`	yes	Supply the internal identifier of the requisition template that the webhook applies to. (It's the 789 in this example: https://lab.ovation.io/orgs/123/projects/456/requisition-settings/789/template-information.)

Response Body

{
	"webhook_endpoints": [{
		"id": 789,
		"target_url": "http://api.test.com/",
		"event": "report_signed",
		...
      	},
	...
  ]
}

Create a Webhook

Use this endpoint to create a new webhook.

HTTP Request

POST /api/v3/project_templates/{projectTemplateId}/webhook_endpoints

Query Parameters

Key	Required	Description
`projectTemplateId`	yes	Supply the internal identifier for the requisitiontemplate that the webhook should apply to. (It's the 789 in this example: https://lab.ovation.io/orgs/123/projects/456/requisition-settings/789/template-information.)

Request Body

{
	"webhookEndpoint": {
		"target_url": "http://api.test.com/",
		"event": "report_signed",
		"username": "someUser",
		"password": "somePassword",
		"requestHeaders": {
			"someKey": "any value",
			"anotherKey": "some other value",
			...
		},
		"authenticationHeaders": {
			"api-key": "1234"
    		}
  	}
}

Field name	Required	Description
`target_url`	yes	Target URL for webhook
`username`	yes	Username for auth
`password`	yes	Password for auth
`event`	yes	Event which triggers the webhook endpoint. Options: report_signed report_corrected sample_rejected requisition_canceled requisition_signed_accession report_ready_for_generation report_correction_ready_for_generation
`requestHeaders`	no	JSON object container key value pairs These will be added as headers in Webhook request Notes: PascalCased, camelCased, and snake_cased keys will be converted to dash-cased keys Ex: `KeyName`, `keyName` and `key_name` will all be treated like `key-name`
`authenticationHeaders`	no	JSON object container key value pairs These will be added as headers in Webhook request Notes: These headers will be stored as encrypted values They will be used instead of basic auth (username/password) PascalCased, camelCased, and snake_cased keys will be converted to dash-cased keys Ex: `KeyName`, `keyName` and `key_name` will all be treated like `key-name`

Response

Response code	Response body
201 Indicating the webhook endpoint was successfully created
401 Indicating an authentication error
422 Indicating an error with the request	Will return the validation errors found. For example: "Project Template not found", "Event not found"

Update a Webhook

Use this API to update an existing webhook.

HTTP Request

PUT /api/v3/project_templates/{projectTemplateId}/webhook_endpoints/{webhookId}

Query Parameters

Key	Required	Description
`projectTemplateId`	yes	Supply the internal identifier of the requisition template that the webhook applies to. (It's the 789 in this example: https://lab.ovation.io/orgs/123/projects/456/requisition-settings/789/template-information.)
`webhookId`	yes	Supply the internal identifier of the webhook. Retrieve this information by using the API to Get Webhooks.

Request Body

Supply the request body described above for Create a Webhook.

Response

Response code	Response body
201 Indicating the webhook endpoint was successfully created
401 Indicating an authentication error
422 Indicating an error with the request	Will return the validation errors found. For example: "Project Template not found", "Event not found"

Delete a Webhook

Use this API to delete an existing webhook.

HTTP Request

DELETE /api/v3/project_templates/{projectTemplateId}/webhook_endpoints/{webhookId}

Use this API to update an existing webhook.

Query Parameters

Key	Required	Description
`projectTemplateId`	yes	Supply the internal identifier of the requisition template that the webhook applies to. (It's the 789 in this example: https://lab.ovation.io/orgs/123/projects/456/requisition-settings/789/template-information.)
`webhookId`	yes	Supply the internal identifier of the webhook. Retrieve this information by using the API to Get Webhooks.

Response

Response code	Response body
201 Indicating the webhook endpoint was successfully deleted
401 Indicating an authentication error
422 Indicating an error with the request