Pollable endpoint for webhookless workflow

[bethesque]

Context

See https://pact.canny.io/feature-requests/p/support-a-polling-endpoint-for-a-webhookless-workflow

Some organisations do not allow connectivity to their CI systems from the Pact Broker for security reasons, which means webhooks can't be used to trigger a provider build when a pact changes.

For these situations, add an endpoint that can be polled by the CI system itself to trigger the required builds.

Potential design

Instead of creating a "triggered webhook" for each event, create an event log in a database table, with a UUID. Each event will have all the templated parameters that are available to a normal webhook.

The CI system (or some trusted intermediary) would poll the endpoint to determine which builds needed to be triggered.

Design decisions

Can the CI system (or what ever process is calling the endpoint) preserve state?

If it can, then it just has to pass in the "last processed UUID" each time, and the Broker can remain stateless.

If it can't keep state, it would need to let the Broker know which events it had processed, so that the broker could return only unprocessed events next time. If there were multiple CI systems running, this might get confusing though.

Do we need to make this configurable?

Apart from "on"/"off", do we need to configure events to any greater granularity? I'm assuming that if anyone needs this endpoint, the entire organisation needs it, rather than just a subset of pacticipants/events.

Clean up

This table could get big fast, and so would need to be cleaned up at some stage. Do we link the events to their pacts/versions so that when the versions get cleaned, the events get cleaned too, or do we have a separate cleanup config.

Potential endpoint format

GET /detected-events?from=6c1d52c3-1220-4324-92ce-76b3d8bb3c5b

{
  "events": [
    {
      "uuid" : "271b8eba-1239-474a-a3f1-5d3be687d121",
      "event_name" : "contract_content_changed",
      "date": "",
      "parameters" : { ...  } // all the usual webhook parameters
    }
  ]
}

[mefellows]

If I understand the use cases correctly, this would be an alternative to this webhookless flow.

The two approaches to circumventing webhook executions from Pactflow would be:

1. Inline, where the consumer uses can-i-deploy to determine if a provider build needs to run, checks out and runs the pact verification step for any providers that don't have results
2. A webhook executor that essentially takes the webhook capability of the Pact Broker, but runs it from a trusted location

The pros of (1) being that no state needs to be managed and it's all managed in a single pipeline. The downside is that it requires access to a providers build to check-out and run locally, which may not be possible.

The pros of (2) being that it's only job is to execute builds, and therefore doesn't need to have any specific knowledge of how to checkout a provider code base and run the build. The downside is that it would need to be a custom job runner somewhere, and would likely need to retain some state to determine what webhooks need executing.

The other downside is that the management of (e.g. retries, reporting and visibility) webhooks is now a responsibility of the user, not Pactflow/Pact Broker.

[YOU54F]

I think this would be a really valuable addition, late night brain dump incoming :)

There are multiple webhook event types

The 'contract content changed' event
The 'contract requiring verification published' event
The 'contract published' event
The 'provider verification published' event
The 'provider verification succeeded' event
The 'provider verification failed' event

If we take the The 'contract requiring verification published' event, as a webhook template, this can be setup for all consumers / all providers, although it probably makes sense to scope it to a single provider.

So if we imagine we may have a template for 1 provider to many consumers.

The event being created when a new contract requiring verification published would be scoped to a consumer-provider pair (integration), but there may be many webhooks ( latest from main, any released/deployed), deduped by provider version.

So for one event, there could be many webhooks fired. ( 1 for main and test env if they had same version, and 1 for prod with a diff version)

Instead of creating a "triggered webhook" for each event, create an event log in a database table, with a UUID. Each event will have all the templated parameters that are available to a normal webhook.

Would we have one event entry, and a way to find out which payloads would be sent in a webhook. Would this want to be statically calculated at the time of the event being created, or at the time of the caller polling for the information. (the prod version at the time of the a contract requiring verification, may differ from a time the poller calls this endpoint - hopefully not, but it would mean the poller has information for an up to date verification, which is probably more useful that the point in time. However the point in time of event creation, would be more in line with current behaviour of the webhook being emitted at the point of event creation.

Do we link the events to their pacts/versions so that when the versions get cleaned, the events get cleaned too, or do we have a separate cleanup config.

There could be an acknowledgement back which will remove the event from the table, or mark it as processed.

In the case of The 'contract requiring verification published' event, this could be off the back of the The 'provider verification published' event which could delete the event entry for that pair

Side thoughts - thinking a bit more, a user wouldn't be creating a webhook template, but for a contract requiring verification published event, would need to know the provider versions, and the provider versions awaiting verification. When each verification is published, the provider_versions_awaiting_verification array have that entry removed, until its empty.

{
  "events": [
    {
      "uuid" : "271b8eba-1239-474a-a3f1-5d3be687d121",
      "event_name" : "contract_content_changed",
      "date": "",
      "parameters" : { ...  } // all the usual webhook parameters
      "provider_versions: ["1","2"],
      "provider_versions_awaiting_verification: ["2"],
    }
  ]
}

With regards to the endpoint format

GET /detected-events?from=6c1d52c3-1220-4324-92ce-76b3d8bb3c5b

What would the UUID be for here? I was thinking when I initially read this that it would be for a webhook, but a webhook requires we have an endpoint URL.

Do we need to make this configurable?
Apart from "on"/"off", do we need to configure events to any greater granularity? I'm assuming that if anyone needs this endpoint, the entire organisation needs it, rather than just a subset of pacticipants/events.

Global on/off sounds good, although I think we could definitely be more configurable, as organisations might have a mix, especially if we advise to share a broker.

• Does the pacticipant opt into polling for an event?
  • Provider wants to listen to 1 or multiple event types?

Might reduce the number of events we store, because we only do it for opted in pacticipants.

If we have the idea of creating a webhook, registering an event listener would be cool, it could use largely the same as the webhooks but without requiring a url/header. The user could opt to provide a webhook template here using the templated variables, so they have a pre-created payload stored for retrieval via the endpoint, but they also get access to our regular templated variables, as proposed in your design