Event Notifications¶

GreyMatter can send event notification via webhooks that notify your application any time an event happens in the system. This is especially useful in the following cases:

When you want to get notified about completion of a request instead of having to poll for it.
When the event is not generated against an API request.
When the service which wants to be notified about the event is not the one responsible for making the API request.

Whenever an event happens in the system, it generates a Notification Object which contains all relevant information about what just happened, including the type of event and the data associated with that event. It is then sent via an HTTP POST request to any configured endpoint URLs you have defined.

Notification Object¶

notification¶

A notification object contains all the data related to an event that occurred in the system.

Attributes

notification_type¶: This is a string representing the type of notification.

version_Number¶: This is a string representing the API version that the notification format is following.

notification_id¶: This is a string representing the unique id of this notification. This is guaranteed to never repeat for a different notification across the system.

notification_data¶: This is a json object that contains the payload of the notification. In most cases, the state of the API resource (for which the notification is being generated) at the time of the notification is passed in this payload.

Subscribing to Notifications¶

Todo

Write this

Receiving a Notification¶

For receiving a notification, you will have to create a webhook endpoint in your system.

Notification data is sent as JSON in the POST request body. The full event details are included and can be used directly, after parsing the JSON.

Responding to a Notification¶

To acknowledge receipt of a notification, your endpoint should return a 2xx HTTP status code. All response codes outside this range, including 3xx codes, will indicate to GreyMatter that you did not receive the notification. This does mean that a URL redirection or a “Not Modified” response will be treated as a failure. GreyMatter will ignore any other information returned in the request headers or request body.

If your endpoint does not successfully receive a notification for any reason, we will continue trying to send the notification after a configurable delay interval and upto a configuration maximum time.

Notification Best Practices¶

If your notification endpoint performs complex logic, or makes network calls, it’s possible that the API call would time out before GreyMatter sees its complete execution. For that reason, you might want to have your notification endpoint immediately acknowledge receipt by returning a 202 HTTP status code, and then perform the rest of its duties.

You might also add the received notifications to a queue and handle the notification in workers taking jobs from the queue.

Notification endpoints might occasionally receive the same notification more than once. We advise you to guard against duplicated notification receipts by making your notification processing idempotent. One way of doing this is logging the notification.notification_ids you’ve processed, and then not processing already-logged notifications.