Polling

Event polling has two primary uses:
  1. Paging through historical events.If you need to backfill a webhook subscription or reprocess missed events, we strongly recommend using our event replay functionality instead. This reduces the complexity of your integration; the SEEK API will take care of requeuing each event in scope, and your webhook endpoint will process a replayed event as it would any other event.If you want to interactively explore historical events you can use the Developer Dashboard’s events page.
  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 the CandidateProfile.associatedPositionProfile from a CandidateApplicationCreated event 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

If you use webhook subscriptions, we strongly recommend using our event replay functionality instead.This section remains as a reference for integrations that use polling-based event delivery.
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
CopyGraphQL Explorer
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 {
            associatedPositionProfile {
              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

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
CopyGraphQL Explorer
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 {
            associatedPositionProfile {
              positionUri
            }
          }
        }
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}
To process all new events the events query should be repeated until hasNextPage is false.

Limits

Polling interval

Once the last page of events has been reached you should not poll again for at least 15 minutes. If you’re polling multiple event streams you must not exceed one events query per minute across your entire SEEK API integration. This is a global limit applied across all of your servers, hirers and webhook subscriptions.If near real-time event delivery is required then webhooks can be used instead. See “why webhooks” for an explanation of why frequent polling is harmful.

Subscription streams

The events query can be used in tandem with filter.subscriptionId to obtain an ad-hoc historical view of the events associated with a particular subscription. This can help you to discover that historical events are missing or unprocessed, which you can subsequently remediate by triggering a replay. We recommend the Developer Dashboard’s webhooks page for ad-hoc troubleshooting of this nature.Polling implementations are approved on a case-by-case basis and are mandated to operate at a partner level. Your production environment must not implement event delivery by polling subscription-scoped event streams. This limitation ensures that the SEEK API can maintain its quality of service and operating costs as partner usage and webhook subscriptions scale over time.
Events: Webhooks
Getting started: Release notes