Receive trail events

​

What you need

• A webhook URL. Entire registers it with your plugin, see Register your plugin. It must answer directly: Entire doesn’t follow redirects.
• contents:read or contents:write. A trail event names a branch and a title, so Entire sends trail events only to plugins that can read contents. Without either permission you still receive ref and installation events, but no trail events, and nothing tells you so.
• An active installation. You receive events for the repositories an installation covers, while it’s active. They stop when the installation is suspended or deleted.

​

Events

• A deleted trail.
• Comments, discussions, reviews or approvals.
• A description edit.
• Any change to a trail that is already closed or merged.

​

Handle duplicates and order

• Deduplicate on delivery_id. It stays the same across retries, so the same delivery can arrive more than once. Answer a repeat with 2xx.
• Expect a commit twice. A push to a trail’s branch sends trail.updated with changes.head_sha and also ref.updated. Key builds and check runs on the commit SHA, and start at most one build per SHA.
• head_sha can be null. trail.opened can arrive before Entire records a commit. Read the branch yourself, or wait for the trail.updated that sets head_sha.
• Order isn’t guaranteed. A retry can arrive after a later event for the same trail. trail is the state at trail.updated_at: ignore an event older than the state you hold.
• actor and trail.author can be null when Entire doesn’t know who acted, such as for a push or a change on the forge.
• Answer 2xx to event types you don’t handle. Entire may add event types to the same URL.

​

Verify a delivery

1. Keep the exact bytes of the request body.
2. Check that the token header’s alg is EdDSA.
3. Verify the signature with the key the header’s kid names, from the delivery JWKS URL Entire gave you at registration, today https://us-east-2.entire-ci-webhooks.entire.io/.well-known/jwks.json. Every region signs with the same key set. Cache it, and fetch it again when you see an unknown kid. Don’t fetch keys from a URL built from iss.
4. Check that iss is https://entire.io or an https origin on a host under entire.io, such as https://us-east-2.entire-ci-webhooks.entire.io.
5. Check that aud is your plugin slug.
6. Check iat and exp. A token is valid for 5 minutes.
7. Compare the body_sha256 claim with the unpadded base64url SHA-256 of the raw body. Do this before you parse the JSON.
8. Reject a jti you’ve already seen. Each attempt, including a retry, carries a new token and jti.

​

Respond

​

With the Go SDK

func webhooks(app *plugin.App) {
	http.Handle("POST /webhook", app.WebhookHandler(func(ctx context.Context, d *plugin.Delivery) error {
		change, err := d.Event.TrailChange()
		if err != nil {
			return nil // not a trail event
		}
		switch d.Event.Type {
		case plugin.EventTrailClosed, plugin.EventTrailMerged:
			tearDownPreview(change.Trail.ID)
		default:
			if change.Trail.HeadSHA != "" {
				enqueuePreview(d.InstallationID, d.APIURL, change.Trail.ID, change.Trail.HeadSHA)
			}
		}
		return nil
	}))
}