Subscriptions enable webhook functionality that notifies external services about specific events in BlueDolphin through HTTP requests. You can configure a subscription with a URL endpoint, select the BlueDolphin events to listen for, set headers for authentication, and choose the HTTP verb.

To explore and interact with the BlueDolphin Public API, refer to the interactive API documentation at: /swagger/index.html.

This article describes how to create a new webhook subscription in your repository.

HTTP response status code	Interpretation
201 Created	Subscription created successfully
400 Bad Request	Subscription could not be created due to an existing subscription, an existing or invalid tenant, or event data passed
401 Unauthorized	Subscription could not be retrieved due to the user not being authorized with the correct API key
409 Conflict	Subscription could not be created as an existing subscription matching the body already exists
500 Internal Server Error	The subscription couldn’t be created due to a server error

Prerequisites:

Make a post request to /subscriptions.

Request

NOTE: You need to use an admin user key to set up a webhook.

The header for your API request
The {tenant} needs to be replaced with the tenant's name
The request body, which includes the following:

Parameter	Required	Type	Description
url	✓	string	The external url to which messages will be sent for the bluedolphin_event.
bluedolphin_event	✓	string	The event topic for which a listener will be created for, with the subscription. `ObjectCreated` `ObjectArchived` `ObjectUpdated`
object_definition_id	✓	string	Unique identifier of an object definition. For example, 000000000000000000000002 An empty value is allowed. It returns all object definitions, e.g.,"" = all object definitions
workspace_id	✓	string	Workspace where the event will take place. For example, 000000000000000000000001. Empty value is allowed, it returns all workspaces, e.g.,"" = all workspaces
status	Optional	boolean	The status of the subscription. By default, subscriptions are created with a status of 0 (disabled). Allowed statuses are, `Disabled = 0` `Enabled = 1`
headers	Optional	Dictionary<string, string>	Any headers required for authorization against the external URL provided
http_verb	Optional	string	The type of request to be made against the external URL provided. Allowed values are GET, POST and PATCH By default, POST requests are made
url	✓	string	The external url to which messages will be sent for the bluedolphin_event.

Trigger Event

Here is the example of what the trigger will look like,

Event type: `ObjectCreated`

{
"url": "https://webhook.site/b2e2a01e-4cd1-4e27-8674-a46b9c1c6fee",
"bluedolphin_event": "ObjectCreated",
"object_definition_id":"532fff94b41281c17ce263b6",
"workspace_id":"6867ac199159e1f95fd8f99e",
"status": 1
}

Event type: `ObjectUpdated`

Changing relationships (also via relation-type question) of an object won’t trigger this type of events.

{
"last_updated_by": "648ffe46c72cc56913c1885a",
"bluedolphin_event": "ObjectCreated",
"url": "https://prod-196.westeurope.logic.azure.com:443/workflows/a6d2beadfbef4a3982478e5022c21334/triggers/manual/paths/invoke?api-version=2016-06-01&sp=%2Ftriggers%2Fmanual%2Frun&sv=1.0&sig=0Jg9bIxBLbEhDrn8I-YWLcQMp9XzhXoPix5ze-eWhj4",
"object_definition_id": "ID",
"workspace_id": "ID",
"status": 0
}

Event type: `ObjectArchived`

{
  "tenant": "gmichels", 
  "objectId": "682462a0fa37bcc1240052ae",
  "object_definition_id":"532fff94b41281c17ce263b6",
  "workspace_id":"6867ac199159e1f95fd8f99e", 
  "title": "Test", 
  "eventType": "ObjectArchived" 
}

Here is an API request example that shows how to create a new webhook with the Event name:

curl --location --globoff 'https://public-api.eu.bluedolphin.app/v1/subscriptions' \

--header 'x-api-key: YOURAPIKEYSECRET'

--header 'tenant:  tenantName’ \

--header 'Content-Type: application/json' \

--data '{
"url": "some external url",
"bluedolphin_event": "Event Name"
"object_definition_id": "000000000000000000000001",
"workspace_id": "000000000000000000000001",
"HEADERS": {
"custom_header": "custom_value"
},
"status": 1,
"http_verb": "POST"
}

Response

A successful call returns a response with a 200 OK HTTP status code and the following body:

{
            "id": "Unique identifier",
            "last_updated_by": "Unique identifier",
            "url": "Unique URL provided",
            "bluedolphin_event": "Event Name",
            "headers": {},
            "status": 1,    
            "http_verb": "POST"
}

Response properties

Property	Type	Description
id	string	Unique identifier for the subscription
last_updated_by	string	Unique identifier of the person who last updated/created the subscription
url	string	The external URL to which messages are sent
bluedolphin_event	string	The event name for which the subscription was created
headers	object	The headers provided if needed, to make a request to an external URL with authorization tokens
http_verb	string	The type of request to be made to the URL provided

Create an Object

Retrieve a Subscription

Retrieve Subscriptions

Update a Subscription

Introduction to Subscriptions

Create a Subscription