Polling

Polling

Event polling has two primary uses:
  1. Paging through historical events, for e.g. backfilling a new webhook subscription or reprocessing missed events.
  2. Event delivery for partners without the capability to consume webhooks.
Both flows use the events query for cursor-based pagination through events.
The events query supports filtering on scheme ID, event types and an optional date range. You can implement more sophisticated event categorisation or filtering within your polling software. For example, you might select a candidate application’s associatedPositionOpening to identify the associated position and hirer.
To avoid wasted resources from repeatedly polling each hirer, filtering events by hirer ID is intentionally unsupported. As an alternative you can use webhooks to deliver events to hirer-specific HTTPS endpoints.

Backfilling & reprocessing flow

Partnerauth.seek.comgraphql.seek.comSend client credentialsIssue partner tokenUse `events` query with `after: null`Return first page of events and `endCursor`Use `events` query with the previous `endCursor`Return events and a new `endCursor`loop[While `hasNextPage`]Partnerauth.seek.comgraphql.seek.com
This flow is based on paging through events within a specific time range:
  • For processing missed or failed events you can specify the afterDateTime and beforeDateTime of the affected period.
  • For backfilling events for a webhook subscription you can specify just the beforeDateTime of when the subscription was created.
You then repeatedly use the events query with the determined afterDateTime and beforeDateTime arguments. The initial query should pass after: null to get the first page.
For example, this queries the first page of 25 CandidateApplicationCreated events between April 10th and 20th 2020:
QueryVariables
query(
  $after: String
  $filter: EventsFilterInput!
  $first: Int!
  $schemeId: String!
) {
  events(after: $after, filter: $filter, first: $first, schemeId: $schemeId) {
    edges {
      node {
        typeCode
        ... on CandidateApplicationCreatedEvent {
          candidate {
            person {
              name {
                formattedName
              }
            }
          }
          candidateApplicationProfile {
            associatedPositionOpenings {
              positionUri
            }
          }
        }
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}
For subsequent queries you pass the previous page’s endCursor as the after argument. Once hasNextPage is false there are no more events in the time range and the process is complete.
Events will remain for 90 days after they occur. Your software must store any data that it needs to access after the 90 day period.

Event delivery flow

Partnerauth.seek.comgraphql.seek.comSend client credentialsIssue partner tokenUse the `events` query with the previous `endCursor`Return events and `endCursor`loop[Every 15 minutes]Partnerauth.seek.comgraphql.seek.com
In this flow the events query is used with the previous poll’s endCursor as its after argument. The cursor is persisted by your software to resume event polling from the last processed event. If it’s difficult to persist the cursor you can instead use webhooks to receive events statelessly.
For accurate paging only the after argument should be used; you should not specify an afterDateTime or beforeDateTime. This ensures that polling will resume from the last successful poll in the event of a failure.
For example, this queries for a page of 25 CandidateApplicationCreated events since the previous cursor:
QueryVariables
query(
  $after: String!
  $filter: EventsFilterInput!
  $first: Int!
  $schemeId: String!
) {
  events(after: $after, filter: $filter, first: $first, schemeId: $schemeId) {
    edges {
      node {
        typeCode
        ... on CandidateApplicationCreatedEvent {
          candidate {
            person {
              name {
                formattedName
              }
            }
          }
          candidateApplicationProfile {
            associatedPositionOpenings {
              positionUri
            }
          }
        }
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}
To process all new events the events query should be repeated until hasNextPage is false.
Once the last page of events has been reached you should not poll again for at least 15 minutes. If real-time event delivery is required then webhooks can be used instead. See “why webhooks” for an explanation of why frequent polling is harmful.
Events
Use cases
Use cases