Marigold Engage Delivery Cloud - Webhooks API (1.0.0)

Team Marigold Engage: info@meetmarigold.com URL: https://developers.meetmarigold.com/engage/

EDC Webhooks

By providing a fully documented API reference, we want to enable everyone to maximize the usage of the Marigold Engage Platform for automating & exchange data.

The Marigold Engage API is organized around the REST protocol with the use of HTTP verbs and a RESTful endpoint structure. The API provides resource-oriented URLs, accepts form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs. We strive to make the endpoints so self-explanatory and informative as possible, by providing clear validation, error and success responses.

The API style is inspired by the Microsoft API guidelines.

REST API

The EDC Webhooks endpoints are segmented.

Base URL

https://<customername>.sdc.slgnt.eu/api

Example: https://<customername>.sdc.slgnt.eu/api/webhooks/v1/admin/subscriptions/

Definition

Application Env name: refers to a unique subdomain per environment. In the example the production environment "sdc-prod".
Module: refers to a unique subdomain per product/application module. For this API reference the module is SMC ( Marigold Engage).
slgnt.eu/slgnt.us: refers to the geographical area for which the customer instance is active.

Europe: https://<customername>.sdc.slgnt.eu/api
Touchpoint: refers to the grouped entrypoint for the user to interact/interface with the application. For this API reference the touchpoint is the API.
Component/Channel: refers to the channels (email/mobile/sms) or towards a specific component (like messages, reporting, …). In the example the channel is "push".

URI parts

https://baseUrl/chapter/versioning/entity(_type)/{identifier}/operation|result

Examples:

- webhooks          https://<customername>.sdc.slgnt.eu/api/webhooks/v1/events/send

Definition

Part 0: Base URL - The base url is a reference to the customer domain.
Part 1: Webhooks - Refers to the EDC Webhooks.
Part 2: Version number - major numbering only - example: v2. In case no version number is part, it refers to the initial API version.
Part 3: Entity(_type) - Refers to entity or entity type. This is depends on the chapter, if it is needed or not.
Part 4: Identifier - Refers to the unique identifier for a specific entity.
Part 5: Operation|Result - Refers to additional operations or specific sub-entities of the parent entity. This is depends on the chapter, if it is needed or not. Examples: lists > fields / journeys > send

Authentication

The Marigold Engage Delivery Cloud API uses the Oauth2.0 authorisation protocol, through bearer JSON Web Tokens (JWT), to authenticate requests. Engage will provide you with a dedicated client ID and secret to authorize using OAuth.

With each API call, you will need to set request headers including your access key to authenticate yourself.

The client ID and secret carry significant privileges. Please ensure to keep them 100% secure. Do not share your Oauth client ID and Oauth client secret in publicly accessible areas such as versioning systems (GitHub, Bitbucket,... ) or client-side code.

Errors

Engage uses the conventional HTTP response codes to indicate successful or failed API requests.

Codes in the 2xx range indicate success.

Codes in the 4xx range indicate an input related error or validation restrictions.

Codes in the 5xx range indicate an error with Marigold Engage servers.

HTTP Status Codes	Description
200 - OK	We found the request resource
201 - Created	The resource is successfully created
204 - No Content	The requested resources is empty
400 - Bad Request	There was an error with the request. The body of the response will have more info.
401 - Unauthorized	The access key was incorrect
404 - Not found	The resources cannot be found
405 - Method Not Allowed	The method is not allowed
408 - Request Timeout	The request is taking too long to respond
409 - Conflict	Something is conflicting the request
422 - Unprocessable Entity	The resource couldn't be created
429 - Too Many Requests	Too many requests hit the API too quickly
5xx - Server errors	Something went wrong on our end. Please try again

400/422 - Bad / Validation request - WIP

In the case of a validation of bad request error, the body of the response includes a JSON formatted response that tells you exactly what's wrong.

Attributes - current - WIP

Attribute	Type	Description
`title`	String	One of a server-defined set of error codes.
`status`	Integer	An integer that represents the error type.
`traceId`	String	A reference ID to trace log within the SMC platform. This can be relevant for reporting to the support team.
`errors[]`	Array	An array of details about specific errors that led to this reported error.
`errors[] key`	Integer	For some errors that could be handled programmatically, a short string indicating the error code reported.
`errors[] array value`	String	A human-readable description of the error. You can use this to let the user know what they can do about the error.

{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
  "title": "One or more validation errors occurred.",
  "status": 400,
  "traceId": "00-03f4894fecc1ae4498599fb8d5d16b5e-9d0a2aab93c57d41-00",
  "errors": {
    "Name": ["The Name field is required."],
    "ApiName": ["The ApiName field is required."]
  }
}

Attributes - proposal - WIP

Attribute	Type	Description
`code`	Integer	An integer that represents the error type.
`message`	String	A human readable error message.
`traceId`	String	A reference ID to trace log within the SMC platform. This can be relevant for reporting to the support team.
`target`	String	The target in your request related to the error.
`details[]`	Array	An array of details about specific errors that led to this reported error.
`errors[].code`	Integer	A short string indicating the error code reported, for some errors that could be handled programmatically.
`errors[].message`	String	A human-readable description of the error. You can use this to let the user know what they can do about the error.
`errors[].target`	String	The target in your request related to the error if the error is specific.

{
  "error": {
    "code": "BadArgument",
    "message": "Multiple errors in ContactInfo data",
    "target": "ContactInfo",
    "details": [
      {
        "code": "NullValue",
        "target": "PhoneNumber",
        "message": "Phone number must not be null"
      },
      {
        "code": "NullValue",
        "target": "LastName",
        "message": "Last name must not be null"
      },
      {
        "code": "MalformedValue",
        "target": "Address",
        "message": "Address is not valid"
      }
    ]
  }
}

OpenAPI specification

We provide the API specification in the format of OpenApi files which can be found in the openapi/ directory:

OpenAPI 3.0 - JSON format
- sdc-webhooks-rest-v1.openapi.json
OpenAPI 3.0 - YAML format
- sdc-webhooks-rest-v1.openapi.yaml

Developer documentation

The Marigold Engage API can provide very powerful manner for integrating, exchanging data and automating tasks. To facilitate with the usage of the API, we have created a number of guides in our development webhooks.

Our getting started guide will demonstrate for a number of basic use cases. It will refer to this API reference us to highlight the implementation and refer to other information resources in Marigold Engage that will be helpful for many other use cases too.

Click here to visit our developer webhooks.

Postman collection

To get you up and running and provide a hands-on experience, we provide an up-to-date Postman collection of the EDC Webhooks API V1.

Import the Postman collection through any of the methods specified below.

Use the link: https://developers.meetmarigold.com/engage/api/sdc-webhooks/postman/sdc-webhooks-rest-v1.postman.json via "Import" > "Link"
Download the file sdc-webhooks-rest-v1.postman.json and import the file via "Import" > "File"
Download the file sdc-webhooks-rest-v1.postman.json and copy the contents and paste in the "Import" > Paste "Raw Text" section.

This collection takes advantage of Postman variables and environments to store/access your Marigold Engage Oauth Client key/secret and base URL.

Sending events

Early Access

Send Events to the Webhook ingestion endpoint.

testing: true

header Parameters

Authorization	string Default: Bearer {{oauth_access_token}} Example: Bearer {{oauth_access_token}} Oauth2 token to authorize requests.
Content-Type required	string Default: application/json Example: application/json Define the file type and format for the request object.

Request Body schema: application/json

The new values

Array

id	string CloudEvents 'id' attribute. Identifies the event. The ID is unique within the scope of the producer.
tenant	string The Marigold Engage tenant reference, which is a combination of the region (EU/US) and the Saasname, formatted like `REGION.SAASNAME`.
source	string <uri> the context in which this event has happend.
type	string CloudEvents 'type' attribute. Type of occurrence which has happened. Often this attribute is used for routing, observability, policy enforcement, etc.
subject	string or null A description / additional info for the event in the context of the specified source.
time	string or null <date-time> Timestamp of when the event happened. Expressed in UTC.
specversion	string Default: "1.0" The version of the CloudEvents specification which the event uses. For more information see cloudEvents
dataschema	string <uri> Represents a URI for the schema to which the data adheres to.
datacontenttype	string Default: "application/json" Content type of the 'data' field provided by the event.
	object CloudEvent 'data' content. The event payload.

Responses

Request samples

Payload

Content type

application/json

[{"id": "f0e01063-efaa-4023-8199-278d4e4285ae",
"tenant": "EU.ENGAGE",
"source": "/sdc/mailer",
"type": "sdc.deliveries.email.sent",
"subject": "674d25d7319b4549a88cefdda049989e_92233793802426",
"time": "2018-04-05T17:31:00.000Z",
"specversion": "1.0",
"dataschema": "http://example.com",
"datacontenttype": "application/json",
"data": {"account_id": "3822afb319684af18b9664ee327b7c44",
"tenant_id": "EU.ENGAGE",
"sender_domain": "example.com",
"route": {"destination": {"cluster_id": "357d2587006d4938a0cc1a9866d731b1",
"domain_name": "#MEETMARIGOLD.COM"
},
"local_ip_port": 5025
},
"outcome": "250 Ok",
"recipient": "sdc.example@slgnt.eu",
"context": {"tags": ["transactional",
"DE"
],
"metadata": "TEST=true",
"profile": "user@userlist"
},
"drop_time_milliseconds": 40.0872,
"external_reference": "674d25d7319b4549a88cefdda049989e_92233793802426",
"timestamp": "2022-03-16T12:56:00.1260605"
}
}
]

Webhook subscriptions

Early Access

Get all webhook subscriptions

testing: true

header Parameters

Authorization	string Default: Bearer {{oauth_access_token}} Example: Bearer {{oauth_access_token}} Oauth2 token to authorize requests.
Content-Type required	string Default: application/json Example: application/json Define the file type and format for the request object.

Responses

Response Schema: application/json

Array

filters	Array of strings Only events that match the filter get forwarded to the target url. The filters support using wildcards ('') at the start, end or both. Wildcards must come before or after the '.' character of the filter part. Examples: 'sdc.', '.failed', '.email.*', 'sdc.deliveries.email.sent'
	Array of objects (WebhookAdvancedFilter) Only events that match the all of the advanced filters get forwarded to the target url. The filters support all the end properties of the event. You have to respect the structure of the event you want to filter. If you try to put a filter on a property that doesn't exists or that is not an end property, the webhook won't be sent. Examples: 'data.recipient stringEndsWith gmail.com', 'data.account_id equals d6862df2-59c2-4fbc-b248-d1374967dafd'
target_url	string The endpoint for posting the event to that matches with the filter.
	Array of objects or null Custom headers that add additional information to the HTTP request. For example this can be used to add basic authentication/authorization. The following headers are restricted and can't be overridden or used: Content-Type Content-Length Connection Host Cache-Control

Response samples

Content type

application/json

[{"filters": ["sdc.*"
],
"target_url": "www.example.com/sdc",
"headers": [{"name": "Authorization",
"value": "Basic TG9uZyBsaXZlIGRvZ2Uh"
}
],
"advanced_filters": [{"key": "data.recipient",
"operator": "stringEndsWith",
"value": "gmail.com"
}
]
},
{"filters": ["sdc.deliveries.email.failed"
],
"target_url": "www.example.com/failed",
"advanced_filters": [{"key": "data.account_id",
"operator": "equals",
"value": "c44f09fd-c184-4173-97ca-547128e24cb4"
}
]
},
{"filters": ["*.deliveries.*"
],
"target_url": "www.example.com/deliveries",
"headers": [{"name": "Authorization",
"value": "Basic TG9uZyBsaXZlIGRvZ2Uh"
},
{"name": "X-Value",
"value": "Extra header"
}
],
"advanced_filters": [{"key": "data.time_to_live",
"operator": "numberGreaterThan",
"value": "300"
}
]
},
{"filters": ["*.failed"
],
"target_url": "www.example.com/failed"
}
]

Update webhook subscriptions on tenant level

Updates the webhook subscription configurations.

testing: true

header Parameters

Authorization	string Default: Bearer {{oauth_access_token}} Example: Bearer {{oauth_access_token}} Oauth2 token to authorize requests.
Content-Type required	string Default: application/json Example: application/json Define the file type and format for the request object.

Request Body schema: application/json

The configuration for a webhook subscription.

Array

filters	Array of strings Only events that match the filter get forwarded to the target url. The filters support using wildcards ('') at the start, end or both. Wildcards must come before or after the '.' character of the filter part. Examples: 'sdc.', '.failed', '.email.*', 'sdc.deliveries.email.sent'
	Array of objects (WebhookAdvancedFilter) Only events that match the all of the advanced filters get forwarded to the target url. The filters support all the end properties of the event. You have to respect the structure of the event you want to filter. If you try to put a filter on a property that doesn't exists or that is not an end property, the webhook won't be sent. Examples: 'data.recipient stringEndsWith gmail.com', 'data.account_id equals d6862df2-59c2-4fbc-b248-d1374967dafd'
target_url	string The endpoint for posting the event to that matches with the filter.
	Array of objects or null Custom headers that add additional information to the HTTP request. For example this can be used to add basic authentication/authorization. The following headers are restricted and can't be overridden or used: Content-Type Content-Length Connection Host Cache-Control

Responses

Request samples

Payload

Content type

application/json

[{"filters": ["smc.*"
],
"target_url": "www.example.com/smc"
},
{"filters": ["sdc.*"
],
"target_url": "www.example.com/sdc",
"headers": [{"name": "Authorization",
"value": "Basic TG9uZyBsaXZlIGRvZ2Uh"
}
],
"advanced_filters": [{"key": "data.recipient",
"operator": "stringEndsWith",
"value": "gmail.com"
}
]
}
]

Response samples

Content type

application/json

{"type": "https://tools.ietf.org/html/rfc7231#section-6.5.4",
"title": "Not Found",
"status": 404,
"detail": "Resource does not exist.",
"instance": "TODO"
}

Delete all webhook subscriptions for a tenant.

Removes webhook subscription configurations for the tenant.

testing: true

header Parameters

Authorization	string Default: Bearer {{oauth_access_token}} Example: Bearer {{oauth_access_token}} Oauth2 token to authorize requests.
Content-Type required	string Default: application/json Example: application/json Define the file type and format for the request object.