Create a Subscription – BlueDolphin

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 must include:

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 with the subscription. The events that are supported, `ObjectCreated` `ObjectArchived` `ObjectUpdated`
object_definition_id	✓	string	Unique identifier of an object definition. For example, 000000000000000000000002 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
last_updated_by	Optional	string	The ID of the user creating the subscription
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 an external URL provided
http_verb	Optional	string	The type of request to be made against the external URL provided. By default, POST requests are made

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.

{
     "boemsChanged": false,
     "propertiesChanged": true,
     "tenant": "gmichels",
     "objectId": "682462a0fa37bcc1240052ae",
     "object_definition_id":"532fff94b41281c17ce263b6",
     "workspace_id":"6867ac199159e1f95fd8f99e",
     "title": "Test",
    "eventType": "ObjectUpdated"
}

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 201 OK HTTP status code and the following body:

{
 "id": "Unique identifier",
"last_updated_by": "Unique identifier",
"url": "Unique URL provided",
"bluedolphin_event": "Event Name",
"object_definition_id": "000000000000000000000001",
"workspace_id": "000000000000000000000001",
  "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
object_definition_id	string	Unique identifier of the object definition that the object is based on
workspace_id	string	Unique identifier of the workspace where the event is located
headers	object	The headers are 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

Request must include:

Response

Response properties

Related articles