Page Comparison

...

WebhookEvent Endpoints

The following are the resources that are available on any given WebhookEvent:

...

Resource

...

Description

...

Request Object

...

Response Object

...

GET /webhook/events

...

Retrieve a batch of events by their eventIds. A common use of this service is after the initial event invocation, a user can retrieve one/many of the events they were given IDs for.

...

GetWebhookEventsRequest

...

GetWebhookEventsResponse

Webhook Invocation

At the time of an event the webhook should be invoked. The process should be multi-step. Once Synapse notes the event initiation, a service will create an WebhookEvent to be distributed to each receiver who has registered for it. Synapse will then distribute each event to the corresponding event-receiver’s endpoint found in their corresponding webhook object. The event will be sent as an HTTP POST request with the eventId contained in the request body. The event-receiver will have the option to require the requests to be authorized with a JWT token. A new token will be exchanged anytime an event occurs and isAuthorizationEnabled is set to true. The token will contain information about the Webhook (i.e. the ID of the webhook, who the intended receiver is, expiration time, and Synapse’s signature) in order for the receiver to verify the request is uniquely for them. The receiver will use a public key provided by Synapse to verify the signature. This authorization would mitigate some of the security concerns with using webhooks as it will provide a way for the event-receiver to verify the event originated from the event-generator if the event-receiver so chooses.

...

{
    "description": "The type of the WebhookEvent.",
    "type": "string",
    "enum": [
        {
            "name": "create",
            "description": "A create has occurred."
        },
        {
            "name": "update",
            "description": "An update has occurred."
        }
        {
            "name": "delete",
            "description": "A delete has occurred."
        }
    ]
}

GetWebhookEventsRequest.json

{
    "description": "The request body of GetWebhookEventsRequest.",
    "properties": {
        "eventIds": {
			"type": "array",
			"description": "The eventId of each Event to retrieve. Maximum of 1,000 IDs per batch."
			"items": {
				"type": "string",
			}
		}
    }
}

GetWebhookEventsResponse.json

{
    "description": "The request body of GetWebhookEventsResponse.",
    "properties": {
        "events": {
			"type": "array",
			"description": "The WebhookEvents retrieved."
			"items": {
				"$ref": "org.sagebionetworks.repo.model.webhook.WebhookEvent.json",
			}
		}
    }
}