Page Comparison

...

The event-generator needs some way to validate the method of reception provided by the event-receiver
The event-generator needs some way to validate the identity of each event-receiver
Vice versaConversely, each event-receiver needs a way to validate the events originates from the generator*
Event-receivers should only be able to register for events they are authorized to read
Event-receivers should only receive events they are authorized to read†
When the generator sends an event, only the event receiver should be able to see it‡

...

As for the webhook invocation process, upon and an event occurring, Synapse will bundle information about said event into a WebhookEvent. This WebhookEvent will persist in Synapse for 2 days before being deleted. Synapse will send the ID associated with the event through an HTTP POST request to the provided endpoint associated with the webhook upon the event occurring. It will then be up to the user to make a request through the GET /webhook/events service to retrieve the events by their IDs.

...

Synapse will be adamant about preventing slow downs on the event-receivers side from slowing down Synapse as well. One of the actions we will take to ensure this is we will not have automatic retires retries upon message failures, similar to how GitHub's webhooks handle failure.

...

Resource	Description	Request Object	Response Object
POST /webhook	Create a new Webhook object. This object serves as registration for a Synapse user to receive events for the specified objectId. The combination of the objectId and invokeEndpoint must be unique for each Webhook.	CreateOrUpdateWebhookRequest	Webhook
GET /webhook/{webhookId}	Get the Webhook corresponding to the provided webhookId.	None	Webhook
PUT /webhook/{webhookId}	Update the Webhook corresponding to the provided webhookId. Note: if the invokeEndpoint is changed upon update or the webhook is re-enabled by the user, the user will be required to re-validate the webhook. If Synapse disables the webhook due to an invalid endpoint, update the endpoint using this service, then re-validate with `PUT /webhook/{webhookId}/valid`. The combination of the objectId and invokeEndpoint must be unique for each Webhook.	CreateOrUpdateWebhookRequest	Webhook
DELETE /webhook/{webhookId}	Delete the Webhook corresponding to the provided webhookId.	None	None
PUT /webhook/{webhookId}/valid	Validate the Webhook of the corresponding ID by providing the validation code received by invokeEndpoint upon creation/updating. After successful validation, Synapse will set `isInvokeEndpointValid` to `true`.	ValidateWebhookRequest	ValidateWebhookResponse
GET /webhook/{webhookId}/test	Test the Webhook of the given webhookId. This will attempt to send the eventId of a generic event to the invokeEndpoint if it the invokeEndpoint is valid. The user can then try retrieving the generic event through `GET /webhook/events`.	None	WebhookEvent
GET /webhook/{userId}/list	List all webhookIds for a Synapse user. Each call will return a single page of WebhookRegistrations. Forward the provided nextPageToken to get the next page.	ListUserWebhooksRequest	ListUserWebhooksResponse

...

Expand

title	org.sagebionetworks.repo.model.webhook.WebhookEvent.json

Code Block

language	json

{
    "description": "A webhook event in Synapse containing information about a change that has occured. Upon the initial event, Synapse users will be sent the ID associated with this WebhookEvent and then will be tasked with retrieving the WebhookEvent by ID through a Synapse RESTful API request.",
    "properties": {
        "eventId": {
            "type": "string",
            "description": "An ID associated with this WebhookEvent."
        },
        "objectId": {
            "type": "string",
            "description": "The ID of the object in Synapse the user would like to receive events for. Currently, support for is enabled for entities, with future plans to support other objects in Synapse as well."
        },
        "objectType": {
			"$ref": "org.sagebionetworks.repo.model.webhook.WebhookObjectType",
			"description": "Which type is Synapse object is associated with the Webhook."
		},
        "eventType": {
			"$ref": "org.sagebionetworks.repo.model.webhook.EventType",
			"description": "Which type of event has occured."
		},
		"concreteType": {
            "type": "string",
            "description": "Indicates which type of object in Synapse this event occurred on. The value is the fully qualified class name, e.g. org.sagebionetworks.repo.model.EntityFileEntity."
        }
    }
}

EventType.json

Expand

title	org.sagebionetworks.repo.model.webhook.EventType.json

Code Block

language	json

{
    "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."
        }
    ]
}

...

Versions Compared

Old Version 23

New Version 24

Key

EventType.json