dehaze

Database events

You can trigger webhooks on any mutations performed on your database via Space Cloud.

Prerequisiteslink

Enable eventinglink

Make sure you have enabled eventing for your Space Cloud cluster. To enable eventing, head over to the Settings tab in the Eventing section:

Eventing config

Check the Enable eventing module checkbox.

Select an Eventing DB and hit Save.

Eventing DB is used to store event and invocation logs.

Other prerequisiteslink

  • Enable logical replication for Postgres, if you want to capture events from Postgres.
  • Enable replica mode in MongoDB, if you want to capture events from MongoDB.

Make sure you have read the limitations of the eventing moule.

Create database event triggerlink

Open a project in Mission Control, head to the Event Triggers section and click on the Add button to open the form below:

Database event trigger

Parameterslink

Trigger Name

Give a unique name for an event trigger. (e.g., welcome-email )

Source

Select Database as the event source.

Database

Select the databases for which you want to create an event trigger. If not provided, then the event trigger will be applicable for all the databases.

Collection/Table Name

Put the table/collection names for which you want to create an event trigger. If not provided, then the event trigger will be applicable for all the tables/collections in the selected databases.

Trigger operation

Select the CRUD operation for which you want to create the event trigger. Can be one of:

  • Insert: When a row/document gets created.
  • Update: When a row/document gets updated.
  • Delete: When a row/document gets deleted.

Webhook URL

The HTTP(s) URL that should get triggered with the event payload on the configured operation. Must be a POST handler.

Advanced settingslink

Retries

The number of times to retry a failed invocation. Default value is 3.

Timeout

Timeout in milliseconds. Default value is 5000.

Delivery mechanismlink

The webhook is delivered over HTTP POST request to the specified webhook URL with the following headers:

Content-Type: application/json

Event payloadlink

The POST body of the webhook is a JSON object which follows the Cloud Events specs:

{
  "specversion": "1.0-rc1",
  "id": "<unique-uuid>",
  "type": "<event-type>",
  "source": "<space-cloud-node-id>",
  "time": "<date-string>",
  "data": {
    "db": "<db-type>",
    "col": "<col-name>",
    "docId": "<document-id>" ,
    "doc": "Object"
  }
}
Key Type Description
specversion String Version of the Cloud Events specifications.
id String A unique identifier of an event.
type String Event type. One of DB_INSERT , DB_UPDATE or DB_DELETE .
source String Unique identifier of a Space Cloud instance.
time String Time at which the event occurred(ISO 8601 format).
data.db String Database type. One of mongodb , sql-postgres or sql-mysql .
data.col String Collection/table on which the event occurred.
data.docId String Unique identifier of a row/document ( id field in SQL databases and _id field in MongoDB).
data.doc Object The document being inserted or updated. Latest document in case of update operation.

For example:

{
  "specversion" : "1.0-rc1",
  "id": "43e32d79-f2bf-41c0-be5f-a75c8c1bcfbf",
  "type": "DB_INSERT",
  "source": "1fb07d5d-b670-468e-ba94-ad5f06a5c053",
  "time": "2019-10-19T12:40:50.053Z",
  "data": {
    "db": "mongodb",
    "col": "authors",
    "docId": "ff4a2ee9-830d-487f-8871-8c8b5a61b0bd" ,
    "doc": {
      "_id": "ff4a2ee9-830d-487f-8871-8c8b5a61b0bd",
      "title": "Getting started with event triggers",
      "is_published": false,
      "created_at": "2019-10-19T12:40:50.053Z"
    }
  }
}

Webhook response structurelink

A 2xx response status code from the webhook target is deemed to be a successful invocation of the webhook. Any other response status results in an unsuccessful invocation that causes retries as per the retry configuration.

Limitationslink

Following are the limitations of the eventing module:

  • Truncating a table doesn’t spawn the corresponding DELETE events.
  • Space Cloud can’t capture events from SQL Server yet.

Have a technical question?

Improve the docs!