Webhook APIs

You can manage webhooks with the following APIs.

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
Did this answer your question? Thanks for the feedback There was a problem submitting your feedback. Please try again later.