- [Notification API](#notification-api)
- [Introduction](#introduction)
- [Register a New Subscription](#register-a-new-subscription)
- [Notification Callback Content](#notification-callback-content)
- [Authentication](#authentication)
# Notification API
## Introduction
DrillPlan's Notification API allows external applications to subscribe to key events within the system. Following the event, DrillPlan will send a POST request to a provided `callback_uri`, together with some context, allowing the external application to trigger further action and business logic e.g.
- Extract some data from DrillPlan's Project Plan API and publish it to another application or database.
- Extract a report from DrillPlan's Reporting API.
- Update an external system with a new state.
- etc.
## Register a New Subscription
To make a new subscription, the subscribing application should issue a POST request to the following endpoint `{baseURL}/v1/notifications/subscriptions/types/{subscriptionType}`:
details
summary
Example cURL
span
POST
Request
small
(click to open)
br
```curl
curl -L -X POST '{baseURL}/notifications/v1/notifications/subscriptions/types/{subscriptionType}' \
-H 'accept: application/json' \
-H 'slb-partition-id: {SlbPartitionId}' \
-H 'appkey: {appKey}' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer {token}' \
--data-raw '{
"subscriber": "DemoApp",
"callback_uri": "{callback_uri}",
"callback_headers": {
"Authorization": "Bearer {token}",
"CustomHeader1": "Personal Header Value 1"
},
"drill_plan_object_types": [
"reporting",
"/geomechanics/api/temperatures",
"/geology/api/formation-tops"
],
"contact_email": "TMurray2@slb.com"
}'
```
br
Where:
- `baseURL` = API URL corresponding to your DrillPlan site
- NAM: [https://api.delfi.slb.com/drillplan/](https://api.delfi.slb.com/drillplan/)
- EUR: [https://eu-api.delfi.slb.com/drillplan/](https://eu-api.delfi.slb.com/drillplan/)
- `subscriptionType` = Any of:
- `ReviewStateChanged`: Raised when an object specified in the `drill_plan_object_types` array, has been reviewed, approved, completed or rejected in DrillPlan.
> This was selected in the example above.
- `PublishData`: Raised when a user selects the "Publish Data" button in the connection portal.
> If this subscription type is selected then a `data_source` must also be provided in the request body, with a matching value used in the [Consumption Hub API](/solutions/drillplan/apis/notificationapi)
- `PlanShared`: Raised when an object specified in the `drill_plan_object_types` array has been shared to the plan in DrillPlan.
- `ProjectCreated`: Raised when a new Project is created in DrillPlan.
- `MasterPlanChanged`: Raised when master plan is changed in DrillPlan.
## Notification Callback Content
Following the event in DrillPlan, a callback will be made to the `callback_uri` provided in the subscription, as a POST request. The body of the request will vary depending on the nature of the subscription. Some examples are provided below:
details
summary
Example Body Received for
i
PlanShared
Notification
small
(click to open)
```json
{
"slb_partition_id": "publicdemo01-osdu-slb",
"site_url": "https://eur.drillplan.delfi.slb.com/",
"drill_plan_plan_id": "3d697b991e084c99a2b786e72d0fc86e",
"drill_plan_project_id": "f267fb27acca41e4857237aff9c91339",
"notification_type": "PlanShared",
"drill_plan_object_types": [
"/Traj/api/trajectories",
"/Traj/api/trajectories",
"/location/api/targets",
"/well/api/wbgs"
],
"content": {
"changes_summaries": [
{
"node_id": "a6cfc8dde4dc58d6877a9704acbf0784",
"change_type": "Modify",
"object_type": "/Traj/api/trajectories",
"wellbore_id": "f32eb82917544f4b9b92dbc9072bbb4d"
},
{
"node_id": "354364f2fe3d583cb8f8eed76260b0f8",
"change_type": "Modify",
"object_type": "/Traj/api/trajectories",
"wellbore_id": "a2a0555f8b0144f4881de92a21893db3"
},
{
"node_id": "5f8622cc23d941c79bf2da76251d3bc8",
"change_type": "Add",
"object_type": "/location/api/targets",
"wellbore_id": "f32eb82917544f4b9b92dbc9072bbb4d"
},
{
"node_id": "71f377a61f095246a2616e493325a172",
"change_type": "Add",
"object_type": "/well/api/wbgs",
"wellbore_id": "ef3b15a9ea4d4bf69317631a39e972ef"
}
]
}
}
```
details
summary
Example Body Received for
i
ReviewStateChange
Notification
small
(click to open)
br
```Json
{
"slb_partition_id": "publicdemo01-osdu-slb",
"site_url": "https://eur.drillplan.delfi.slb.com/",
"drill_plan_plan_id": "9168ec42639b4049b163ee8690882a6d",
"drill_plan_project_id": "65496022660a467f93c524ecf365dbf2",
"notification_type": "ReviewStateChanged",
"drill_plan_object_types": [
"/geomechanics/api/temperatures"
],
"content": {
"status": "Completed",
"wellbore_id": "00b8079c73e14686a446399d3ef83060",
"section_id": "ef10024ad11545978c6411e10b9ede39",
"artifact_type": "/geomechanics/api/temperatures",
"artifact_link": "/geomechanics/api/temperatures/16e95464f1244cf0b261ead9d0aa3ca1/versions/4",
"node_id": "1c54e86cc75959dc828de8ecf960d897"
}
}
```
details
summary
Example Body Received for
i
ProjectCreated
Notification
small
(click to open)
br
```Json
{
"slb_partition_id": "publicdemo01-osdu-slb",
"site_url": "https://eur.drillplan.delfi.slb.com/",
"drill_plan_project_id": "65496022660a467f93c524ecf365dbf2",
"notification_type": "ProjectCreated",
}
```
details
summary
Example Body Received for
i
MasterPlanChanged
Notification
small
(click to open)
br
```Json
{
"slb_partition_id": "publicdemo01-osdu-slb",
"site_url": "https://eur.drillplan.delfi.slb.com/",
"drill_plan_plan_id": "9168ec42639b4049b163ee8690882a6d",
"drill_plan_project_id": "65496022660a467f93c524ecf365dbf2",
"notification_type": "MasterPlanChanged",
"content": {
"previous_master_plan_id": "abcdec8a34564049b163aa8698436ddd",
}
}
```
### Authentication
The 'Notification API' is designed to adapt to various authentication systems, enabling subscribers to seamlessly incorporate it into their current authentication processes. Subscribers have the ability to modify their subscription and associated headers as often as needed, which facilitates the use of diverse authentication techniques, such as:
- Authorization: Basic {base64encodedstring}
- Authorization: Bearer {token}
- X-API-Key: {apiKey}
- and more.
While the specific architecture may vary, one example is provided below where a service periodically generates a token from an Authorization Server, updates the subscription using the DrillPlan 'Notification API' and validates the inbound calls received by checking the `Bearer token` contained in the `Authorization` header. This could be validated by using an Introspection Request to the Authorization server or using a public key and token signature.
details
summary
Example UML Diagram
i
(encoded in mermaid)
small
(click to open)
br
```mermaid
sequenceDiagram
participant A as Application
participant CAS as Customer Authorization Service
participant D as DrillPlan Notification API
actor user as User
Note over A,CAS: Customer System
loop e.g. every 60 mins
A ->> CAS: Request token
Note left of CAS: 💬 Will be used to authorize
callback from DrillPlan
CAS -->>A: {customer_oauth_token}
A ->> D: Update subscription with new token
Note over A,D: POST /notifications/subscriptions/types/{subscriptionType}
{..."callback_headers":{"Authorization":"Bearer {customer_oauth_token}"}...}
D -->> A: subscription updated
end
rect rgb(191, 223, 255)
user ->> D: Triggers event: e.g. 'PlanShared'
D ->> A: POST {callback_uri} with event details
Note over A,D: 💬 All headers defined in subscription call will be included.
e.g. -H "Authorization": "Bearer {customer_oauth_token}"
A ->> A:Authentication & authorization
using {customer_oauth_token}
Note right of A: 💬 e.g. Introspection Request to Authorization service
or analysing public key and token signature
A -->>D: status
end
```