Available Webhooks

Configuration

To configure a webhook target, we require the following information:

  • The URL target to which the webhook will POST. We recommend using an HTTPS (secure) target. Note that GET is not provided due to the possibility of payload sizes in excess of 2048 characters.
  • The webhook types (Assessment and Job Fit) to which to subscribe.
  • The webhook type events to which you wish to subscribe.
  • The data format you wish to receive – JSON, XML, CSV, or form-multipart.
  • Any static headers you require to be added.

Optionally, you can specify a port number. If no port number is specified then it will be inferred from the protocol (HTTP or HTTPS). The allowed ports are 80, 443, and 8000.

We can configure multiple webhook targets. For example, if you want assessment information going to one URL and job fit information to another, then please specify each configuration.

Testing

Once your webhook target(s) are configured, we will provide a URL to which you can POST the data values you want echoed by the webhook back to your URL target. The webhook test function does not ensure that the inbound data you send it is valid. Its main function is to help you validate connectivity, the inbound format, headers, and hash comparison functions.

For developers testing behind a firewall, we recommend (and use) the NGrok reverse proxy.

Delivery

The webhook is throttled to perform no more than one outbound call per second. To better handle bursts of activity, we combine up to 100 events in a single call. Therefore, if your target format is JSON, you should expect to parse an array of 1 to 100 events. If your system is under heavy load - for example, a job has been modified and we are recalculating thousands of match scores - then events will queue and be delivered in order. If there are 100,000 events in your queue, then it will take no less than (100,000 / 100) seconds = 1000 seconds to deliver the data.

Under a normal load, you can expect near-real time delivery of webhook events.

Headers

The webhook will add the following headers to every call to your URL target:

  • X-Sha256Digest
    You can use this value to validate that the data you receive from the webhook was sent from our system and was not tampered while in transit.

    To compute the X-Sha256Digest on your system for comparison:

    • ToHash = a string that combines your URL target and the data payload.
    • HashKey = a SHA 256 HMAC hash created using ToHash. Your private API key is the secret key.

    To validate the data you received:

    • CompareToHash = a string that combines your URL target and the payload extracted from the inbound HTTP call. The payload is the data portion of the HTTP call (which follows the headers). Do not include the headers.
    • CompareHashKey = a SHA 256 HMAC hash created using CompareToHash. Your private API key is the secret key.
    • If CompareHashKey and the value in the X-Sha256Digest header are equal, then the data originated from our system intact.
  • Headers you specify, if any.
    Please provide a list of the header names and values you want included. These headers cannot be computed - static header values only.

Retry Schedule

We make every reasonable attempt to deliver your event messages. However, we cannot retry indefinitely. For timeouts or any other response (404, 500, etc.), we follow the schedule below.

  • Post message near real time. If 2xx not received from target, then
  • Retry 60 seconds later. If 2xx not received from target, then
  • Retry 5 minutes later. If 2xx not received from target, then
  • Retry 1 hour later. If 2xxx not received from target, then
  • Retry 24 hours later. If 2xxx not received from target, then
  • Retry 24 hours later. If 2xxx not received from target, then
  • Retry 24 hours later. If 2xxx not received from target, then
  • Stop retrying and eliminate activity message.
    7 attempts over 77 hours before eliminating message.

A message is successfully delivered when we receive a 2xx (anything between 200 and 299) from the target. Once delivered, a message will never be resent. Once eliminated following multiple retries, a message cannot be recovered.

Message Origin

Messages may originate from a variety of IP addresses in our system. These IP addresses are dynamically assigned and will change without notice. Therefore, you should not whitelist inbound traffic from a specific IP address. Rather, use the X-Sha256Digest header to ensure the validity of inbound data to your URL target.

Delivery Timeout

When your listener receives a message, it must reply with a 2xx within 3000 milliseconds. Otherwise, the posting attempt will timeout and re-queue for later delivery. This is to ensure that the webhook connection is rapidly opened and closed.

Therefore, your listener’s architecture must not synchronously perform long-running operations, such as retrieving reports, before replying OK to the webhook. We recommend that your listener posts the inbound message to a message queue or database for asynchronous processing or forks a new thread after replying OK to process the message. This will help ensure your listener is not overwhelmed if a large burst of messages is pushed through the webhook.

Delivery Order

Event messages may not be delivered in the exact order they occurred. The outbound webhook queue is multithreaded and may send batches of messages slightly out of order during periods of high activity. Messages retried due to failure will also arrive out of order. Always look at the event’s EventTime value (UTC, Unix format) when deciding what action to take when a message is received.

Extended Failure Auto Shutdown

If all posts to your URL target fail over a 96 hour period, then the webhook will be automatically disabled for all activity until you manually re-enable it. This is necessary to ensure that an abandoned URL target does not continue to consume system and bandwidth resources.

What Do I Do With The Message?

That is up to you. For example, when you receive a “completed” message, your system might call the Berke API to download the report for the completed assessment, then email it to your end-user.

Note that we do not recommend downloading every report for every job for every participant. It wastes bandwidth and storage space. Rather, download reports as your users request them to ensure the requested report is always up-to-date with the latest job configuration, report enhancements, and assessment data. Our API provides three methods for generating reports:

  1. SendReport
    Email a report
     
  2. GetReportForJob
    Downloads a report PDF from the Berke API
     
  3. GetReport
    Anonymous URL, no authentication required (not for long-term storage)

Assessment Webhook

The Assessment Webhook reports assessment activity, including provisioning, starting, completing, emailing invitations and reminders, and the assessment's current completion status.

Assessment Events

  • 101: Assessment Created
    Raised when an assessment is created.
    Scores and reports will not be available for the assessment until a 106: Assessment Completed event is raised.
     
  • 102: Assessment Invitation Sent
    Raised when an assessment invitation is emailed.
     
  • 103: Assessment Reminder Sent
    Raised when an assessment reminder is emailed.
     
  • 104: Assessment Started
    Raised when a participant starts the assessment.
     
  • 105: Assessment Percent Complete Changed
    Raised anytime an assessment’s approximate percent complete changes.
    This value changes at the end of each section – not on a per question basis. It is computed using the average remaining time to complete, so it is an approximate value.
    Do not use this value to track whether an assessment is complete. Rather, use the 106: Assessment Completed event to track completion status.
     
  • 106: Assessment Completed
    Raised when an assessment is completed.
    Scores will be transmitted shortly if you are subscribed to events 201 or 202. Reports can now be requested for the assessment.
     
  • 107: Assessment Re-Opened
    Raised when an assessment is re-opened.
    This occurs when a job that requires additional assessment data is assigned to a complete assessment. Once an assessment is re-opened, all prior scores become invalid and reports cannot be requested. Once the assessment is closed again, fresh scores will be transmitted if you are subscribed to events 201 or 202 and reports will be available again. If you are caching scores and/or reports in your system, you should clear them when you receive this event.
     
  • 108: Assessment Deleted
    Raised when an assessment is deleted.
    Deleted assessments cannot be un-deleted and all scores and reports for a deleted assessment are invalid and no longer available.
     
  • 109: Assessment Component Opened
    Raised when an assessment component, such as Personality or Logical Problem Solving, is first viewed by a participant. NOTE: This event appends an additional ComponentOpened object in the payload. Please review the payload information below.
     
  • 110: Start Later Email Sent
    Raised when participant says “send me a link so I can do this later”.
     
  • 112: Name Mismatch Reported
    Raised when the participant reports receiving someone else’s assessment. When this happens, an administrator needs to determine which assessment(s) need to be fixed/deleted/provisioned/etc.
    NOTE: This event appends an additional NameMismatch object in the payload. Please review the payload information below.

Assessment Event Payload

Data can delivered by POST in JSON, XML, CSV, or form-multipart format to a URL target. Note that multiple events may be bundled in a single call, so you should expect an array of events of no less than 1 element.

  • string AssessmentUrl
    Full URL to start the assessment. This field will be empty if the assessment is complete.
     
  • string AsessmentKey
    The unique assessment key used to start the assessment.
     
  • string SourceCandidateId
    The ID assigned by your system when the assessment was created. If you did not assign an ID, a GUID was assigned.
     
  • string Job
    Name of the job for which the participant is being assessed.
     
  • string SourceJobId
    The ID of the job for which the participant is being assessed.
     
  • string FirstName
    The participant's first name.
     
  • string LastName
    The participant's last name.
     
  • string Title
    NotCaptured, Mr, Mrs, or Miss. This value will be NotCaptured until the Name section is complete. This value is used to derive gender for the purpose of pronoun replacement (he/she, his/her, etc.) when generating reports. The Berke Assessment does not use gender for any other purpose. This value is self-selected and confirmed by the participant. If a report is generated with incorrect gender pronouns, you can update the participant's title using the UpdateAssessment API method.
     
  • string EmailAddress
    The participant's email address, if captured in the Name section or provided during provisioning. You can require capture of this value at Setup | Personalize | Assessment | Contact Information. (Berke login required)
     
  • string PhoneNumber
    The participant's phone number, if captured in the Name section. You can require capture of this value at Setup | Personalize | Assessment | Contact Information. (Berke login required)
     
  • int SectionsComplete
    Number of sections the participant has completed.
     
  • int SectionsRemaining
    Number of sections the participant still has to complete.
     
  • int PercentComplete
    The participant’s estimated percent complete. This number is updated at the end of each section – not on a per question basis – and is based on average time to complete the sections measured by the assigned job.
     
  • int ApproximateRemainingSeconds
    The estimated remaining seconds to complete the assessment. This number is updated at the end of each section – not on a per question basis – and is based on average time to complete the sections measured by the assigned job.
     
  • string ApproximateRemainingTime
    A label describing the approximate remaining time, such as "less than 15 minutes".
     
  • double TimeStampUtc
    The time when the event occurred converted to Unix time and offset to UTC. Review http://www.epochconverter.com/ if you are unfamiliar with this format.
     
  • [Conditional] object ComponentOpened
    Object that describes the component that was opened. This object will only be reported when event type 109 is raised.
     
    • string Section
      Describes the section the participant opened. Most sections only have a single component, but some, such as personality, have 2 or more components.
       
    • string Component
      Describes the component (part, portion, etc.) that the participant is in within a given section. Most sections only have a single component.
       
  • [Conditional] object NameMismatch
    Object that describes name mismatch information. This object will only be reported when event type 112 is raised.
     
    • string UserReportingIssueName
      Full name of the user who reported the name mismatch. For example, if Jackson Pollock opens Jeff Adkisson’s assessment, this value will be Jackson Pollock.
       
    • string UserReportingIssueEmail
      Email address of user who reported the name mismatch. For example, if Jackson Pollock opens Jeff Adkisson’s assessment, this value will be Jackson Pollock’s email address.
       
    • string CurrentlyAssignedTo
      > Name on the assessment the reporting user is reporting as mismatched. For example, if Jackson Pollock opens Jeff Adkisson’s assessment, this value will be Jeff Adkisson.
       
    • string HiringManagerName
      Name of the hiring manager related to the name mismatched assessment. This will be your API user if the assessment was provisioned via the Berke API.
       
    • string HiringManagerEmail
      Email address of the hiring manager related to the name mismatched assessment. This will be your API user’s email address if the assessment was provisioned via the Berke API.
       
    • string Company
      The company name on your account.
       
    • string Department
      Department related to the assessment. If your account has no departments, then this will match your company name.
       
    • string Message
      A descriptive message describing the details of the name mismatch. There is no information in the Message property that is not found in other reported properties, but you might find it convenient as it describes the most common name mismatch scenarios.

Assessment Payload Example: JSON POST

[
  {
    "AssessmentUrl": "https:\/\/example.assessment.url\/ZZZ123ABC\/Jeff_Adkisson",
    "AssessmentKey": "ZZZ123ABC",
    "SourceCandidateId": "daa06a4-fdf6-4fe1-bca1-2983f88ac9aa",
    "Job": "Webhook Developer",
    "SourceJobId": "webhook_dev",
    "FirstName": "Jeff",
    "LastName": "Adkisson",
    "SectionsComplete": 2,
    "SectionsRemaining": 9,
    "PercentComplete": 5,
    "ApproximateRemainingSeconds": 3570,
    "ApproximateRemainingTime": "an hour or less",
    "TimeStampUtc": 1447988244.7782,
    "ComponentOpened": {
      //IMPORTANT NOTE!
      //This section is specific to event ID 109, component opened,
      //and will not appear in other assessment event messages
      "Section": "Welcome",
      "Component": "Welcome",
      "AverageDurationSeconds": 30
    },
    "NameMismatch": {
      //IMPORTANT NOTE!
      //This section is specific to event ID 112, name mismatch
      //reported, and will not appear in other assessment event messages
      "NameMismatch": {
      "UserReportingIssueName": "Jackson Pollock",
      "UserReportingIssueEmail": "Jackson@NotRealAddress.com",
      "CurrentlyAssignedTo": "Jeff Adkisson",
      "HiringManagerName": "HighMatch Support",
      "HiringManagerEmail": "Support@HighMatch.com",
      "Company": "E-Corp",
      "Department": "Security Dept"
      "Message": "Jackson Pollock is reporting that assessment he\/she received was intended for Jeff Adkisson, so Jackson Pollock's assessment was halted. Possible causes include 1) both people were sent the same invitation, or 2) the invitation for Jeff Adkisson was emailed to Jackson Pollock, or 3) Jeff Adkisson shared his\/her unique invitation with Jackson Pollock, or 4) Jackson Pollock did not understand that he\/she can correct minor problems with his\/her name during the assessment. Please correct this problem, then contact the appropriate parties with the updated assessment invitations. Jeff Adkisson is with Berke Assessment by HighMatch and was invited by HighMatch Support at support@highmatch.com."
    },
    "Event": {
      "WebHookType": "Assessment",
      "WebHookTypeId": 1,
      "EventTypeId": 109,
      "EventType": "AssessmentComponentOpened",
      "EventTypeLabel": "Component Opened"
    }
  },
  // subsequent messages of same webhook type - always plan for an
  // array of events to be received. we will combine bursts of assessment
  // events into a single post
]

HTTP Headers

  1. Connection: Keep-Alive
  2. Accept: application/json,application/xml,text/json,text/x-json,text/javascript,text/xml
  3. Accept-Encoding: gzip,deflate
  4. Host: localhost:9090
  5. User-Agent: Berke Assessment Webhook
  6. X-Sha256Digest: 4a3e5515a5ea0020e37518614303492259d4b536473e6b5c136eb0b9641de1dc

Job Fit Webhook

The Job Fit Webhook reports match scores related to an assessment. When an assessment is completed, we score the assessment against all of the jobs in your account and can report them via this webhook. This webhook will also report scores when new jobs are added to your account or existing jobs are changed and subsequently re-scored.

Job Fit Events

  • 201: Job Fit Scored
    Raised when a job fit is created for a job/assessment combination. If you have multiple jobs, then you will see this event raised for each job in your account when a participant completes an assessment. This event will also be raised when a job is modified, which re-evaluates all matches related to the job.
     
  • 202: Job Fit Primary Job Scored
    Assessments are always performed against a primary job. Unlike the Job Fit Scored event, this event only occurs against the primary job. If you do not want all of the job fit scores for a participant to be raised, choose this event.

Job Fit Payload

Data can delivered by POST in JSON, XML, CSV, or form-multipart format to a URL target. Note that multiple events may be bundled in a single call, so you should expect an array of events of no less than 1 element.

  • string SourceCandidateId
    The ID assigned by your system when the assessment was created. If you did not assign an ID, a GUID was assigned.
     
  • string Job
    Name of the job for which the participant is being assessed.
     
  • string SourceJobId
    The ID of the job for which the participant is being assessed.
     
  • string FirstName
    The participant's first name.
     
  • string LastName
    The participant's last name.
     
  • double Score
    The participant's overall job fit score. This is a value between 0 and 100. Higher values indicate a closer match to the ideal participant for a given job. A high match is greater than 66.6, a medium match is greater than 33.3, and a low match is anything less than or equal to 33.3.
     
  • int MatchLevelId
    3 = High, 2 = Medium, 1 = Low, 4 = Match Disabled in Job, or 5 = Not Enough Assessment Data
     
  • string MatchLevel
    High, Medium, Low, Match Disabled in Job, or Not Enough Assessment Data
     
  • boolean IsCandidatesPrimaryJob
    If true, then match score is for the job assigned to the participant (almost always the job used to assess the participant). If false, then the score is for another job in your account. We score all participants against all jobs.
     
  • string AnonymousReportLinkUrl
    If anonymous report links are enabled, this field will contain a secure, permalink URL that can be used to download the PDF report related to the assessment/job combination being raised without a Berke login. If anonymous report links are disabled, then this field will be empty. In that case, you will have to retrieve reports via an API call.
     
  • double TimeStampUtc
    The time when the event occurred converted to Unix time and offset to UTC. Review http://www.epochconverter.com/ if you are unfamiliar with this format.

Job Fit Payload Example: JSON POST

[
  {
    "SourceCandidateId": "dd644a0-bccd-40a6-a66e-71c4fb0491e7",
    "SourceJobId": "mapped_job_id",
    "FirstName": "Jeff",
    "LastName": "Adkisson",
    "Job": "Job Name Here",
    "Score": 0.75,
    "MatchLevelId": 3,
    "MatchLevel": "High",
    "IsCandidatesPrimaryJob": true,
    "AnonymousReportUrl": "https:\/\/example.assessment.url\/Rpt\/HVFWZTXEJPHZSH",
    "TimeStampUtc": 1447970904.4872,
    "Event": {
      "WebHookType": "JobFit",
      "WebHookTypeId": 2,
      "EventTypeId": 202,
      "EventType": "JobMatchPrimaryJobScored",
      "EventTypeLabel": "Job Match Primary Job Scored"
    }
  },
  // subsequent messages of same webhook type - always plan for an
  // array of events to be received. we will combine bursts of job fit
  // events into a single post
]

HTTP Headers

  1. Connection: Keep-Alive
  2. Accept: application/json,application/xml,text/json,text/x-json,text/javascript,text/xml
  3. Accept-Encoding: gzip,deflate
  4. Host: localhost:9090
  5. User-Agent: Berke Job Match Webhook
  6. X-Sha256Digest: be53c9eb3149b6e30048d3b6ef98da128ac786cad5f81b5637e3c218443b3a89

Assessment Email Tracking Webhook

The Assessment Email Tracking Webhook reports when email messages related to an assessment occur, including delivery, opens, bounces, and spam notifications.

NOTE: Mail tracking has numerous significant caveats due to the arms race between spammers and spam detection systems. Unfortunately, legitimate mail from high-reputation businesses is often misclassified as spam and useful data, such as click tracking, is unavailable because the technique has been exploited by spammers. Please read the mail tracking documentation carefully to avoid setting an unrealistic expectation with your end users.

Assessment Email Tracking Events

  • 300: EmailTrackingAssessmentInvitationBounced
    Raised when Berke mail system is informed that an invitation emailed to a participant bounced or was dropped because the address is improperly formatted. This can also occur if the target mail system is too busy to receive mail at the time of delivery.
     
  • 301: EmailTrackingAssessmentInvitationClicked
    Raised when the mail system is informed that an invitation emailed to a participant was clicked.
    NOTE: This event is presently disabled/unavailable because click tracking increases the likelihood of an invitation being considered spam by automated monitoring systems. We will enable this event if a future mail standard or technique is developed that prevents miscategorization of click-tracked messages.
     
  • 302: EmailTrackingAssessmentInvitationDelivered
    Raised when Berke mail system is informed by the target mail system that the invitation was delivered.
    NOTE: This does not mean the invitation definitely arrived in your participant's Inbox. Some mail systems do not report bounces, spam notifications, etc. Therefore, a delivery event does not always indicate that your participant will see the invitation. Most reports of "I didn't get the invitation" are due to the target mail system misclassifying the invitation as spam, but reporting to the Berke system that the message was successfully delivered.
     
  • 303: EmailTrackingAssessmentInvitationOpened
    Raised when the Berke email system is informed by a small tracking tag that an invitation was viewed by a client connected to the target mail domain.
    NOTE: This does not always mean that the message was viewed by your participant, though it is generally a reliable indicator. Furthermore, some mail clients strip out the tracking tag, so a missing open event does not necessarily indicate that the message was not opened.
     
  • 304: EmailTrackingAssessmentInvitationMarkedSpam
    Raised when the recipient of your invitation explicitly marks an invitation as spam. When this occurs, Berke will prevent further messages of any type from being delivered to that email address. This is to ensure our mail reputation is not damaged, which leads to poor delivery for everyone. Sending unsolicited invitations is prohibited for this reason.
    NOTE: This event will likely only be raised by participants using a major mail vendor, such as Gmail, Yahoo, or AOL. Private mail systems and corporate mail servers rarely report when a message is classified as spam. Therefore, you will not always be notified when a message is marked as spam. Furthermore, a mail system that classifies your message as spam may report to Berke that your message delivered successfully (event 302).
     
  • 305: EmailTrackingAssessmentReminderBounced
    Raised when Berke mail system is informed that a reminder emailed to a participant bounced or was dropped because the address is improperly formatted. This can also occur if the target mail system is too busy to receive mail at the time of delivery.
     
  • 306: EmailTrackingAssessmentReminderClicked
    Raised when the mail system is informed that a reminder emailed to a participant was clicked.
    NOTE: This event is presently disabled/unavailable because click tracking increases the likelihood of a reminder being considered spam by automated monitoring systems. We will enable this event if a future mail standard or technique is developed that prevents miscategorization of click-tracked messages.
     
  • 307: EmailTrackingAssessmentReminderDelivered
    Raised when Berke mail system is informed by the target mail system that a reminder was delivered.
    NOTE: This does not mean the reminder definitely arrived in your participant's Inbox. Some mail systems do not report bounces, spam notifications, etc. Therefore, a delivery event does not always indicate that your participant will see the reminder. Most reports of "I didn't get the reminder" are due to the target mail system misclassifying the reminder as spam, but reporting to the Berke system that the message was successfully delivered.
     
  • 308: EmailTrackingAssessmentReminderOpened
    Raised when the Berke email system is informed by a small tracking tag that an reminder was viewed by a client connected to the target mail domain.
    NOTE: This does not always mean that the message was viewed by your participant, though it is generally a reliable indicator. Furthermore, some mail clients strip out the tracking tag, so a missing open event does not necessarily indicate that the message was not opened.
     
  • 309: EmailTrackingAssessmentReminderMarkedSpam
    Raised when the recipient of your invitation explicitly marks a reminder as spam. When this occurs, Berke will prevent further messages of any type from being delivered to that email address. This is to ensure our mail reputation is not damaged, which leads to poor delivery for everyone. Sending unsolicited messages is prohibited for this reason.
    NOTE: This event will likely only be raised by participants using a major mail vendor, such as Gmail, Yahoo, or AOL. Private mail systems and corporate mail servers rarely report when a message is classified as spam. Therefore, you will not always be notified when a message is marked as spam. Furthermore, a mail system that classifies your message as spam may report to Berke that your message delivered successfully (event 307).
     
  • 310: EmailTrackingAssessmentStartLaterBounced
    Raised when Berke mail system is informed that a "Start Later" message requested by a participant bounced or was dropped because the address is improperly formatted. This can also occur if the target mail system is too busy to receive mail at the time of delivery.
     
  • 311: EmailTrackingAssessmentStartLaterClicked
    Raised when the mail system is informed that a "Start Later" message emailed to a participant was clicked.
    NOTE: This event is presently disabled/unavailable because click tracking increases the likelihood of a "Start Later" message being considered spam by automated monitoring systems. We will enable this event if a future mail standard or technique is developed that prevents miscategorization of click-tracked messages.
     
  • 312: EmailTrackingAssessmentStartLaterDelivered
    Raised when Berke mail system is informed by the target mail system that a "Start Later" message was delivered.
    NOTE: This does not mean the "Start Later" message definitely arrived in your participant's Inbox. Some mail systems do not report bounces, spam notifications, etc. Therefore, a delivery event does not always indicate that your participant will see the "Start Later" message. Most reports of "I didn't get the Start Later message" are due to the target mail system misclassifying the reminder as spam, but reporting to the Berke system that the message was successfully delivered.
     
  • 313: EmailTrackingAssessmentStartLaterOpened
    Raised when the Berke email system is informed by a small tracking tag that a "Start Later" message was viewed by a client connected to the target mail domain.
    NOTE: This does not always mean that the message was viewed by your participant, though it is generally a reliable indicator. Furthermore, some mail clients strip out the tracking tag, so a missing open event does not necessarily indicate that the message was not opened.
     
  • 314: EmailTrackingAssessmentStartLaterMarkedSpam
    Raised when a participant explicitly marks a "Start Later" message as spam. When this occurs, Berke will prevent further messages of any type from being delivered to that email address. This is to ensure our mail reputation is not damaged, which leads to poor delivery for everyone. Sending unsolicited messages is prohibited for this reason.
    NOTE: This event will likely only be raised by participants using a major mail vendor, such as Gmail, Yahoo, or AOL. Private mail systems and corporate mail servers rarely report when a message is classified as spam. Therefore, you will not always be notified when a message is marked as spam. Furthermore, a mail system that classifies a "Start Later" messageas spam may report to Berke that the message was delivered successfully (event 312).
     

Assessment Email Tracking Payload

Data can delivered by POST in JSON, XML, CSV, or form-multipart format to a URL target. Note that multiple events may be bundled in a single call, so you should expect an array of events of no less than 1 element.

  • string SourceCandidateId
    The ID assigned by your system when the assessment was created. If you did not assign an ID, a GUID was assigned.
     
  • string Description
    A formatted description of the event, suitable for logging. This description may have technical information in it, so it is not generally appropriate for revealing to non-technical users.
     
  • string EmailAddress
    The email address to which the message was sent.
     
  • string UserAgent
    Will be empty unless an Open event or Click event is being reported. The UserAgent property is the client's email application or browser.
     
  • string UrlClicked
    Will be empty unless a Click event is being reported. The UrlClicked property is the URL the user clicked.
    NOTE: All click tracking events are presently disabled/unavailable because click tracking increases the likelihood of a reminder being considered spam by automated monitoring systems.
     
  • string IpAddress
    The IP address used to send the email message. This is useful for troubleshooting when a mail target is denying traffic from a specific IP address.
     
  • string ServerResponse
    Message the target domain server gave when contacted by the Berke mail system. This is useful for troubleshooting when a mail target is denying traffic. This response is generally very technical, so we do not recommend presenting it to non-technical end-users.
     
  • double TimeStampUtc
    The time when the event occurred converted to Unix time and offset to UTC. Review http://www.epochconverter.com/ if you are unfamiliar with this format.

Assessment Email Tracking Payload Example: JSON POST

[
  {
    "SourceCandidateId": "berke_77b95e58c8904e0bba7c9169190a7b48",
    "Description": "Mail server said '550 5.1.1 The email account that you tried to reach does not exist. Please try double-checking the recipient's email address for typos or unnecessary spaces. Learn more at  https:\/\/support.google.com\/mail\/answer\/6596 190si2150397oie.264 - gsmtp.",
    "EmailAddress": "please-bounce@berke.as",
    "UserAgent": "",
    "UrlClicked": "",
    "IpAddress": "167.89.43.120",
    "ServerResponse": "550 5.1.1 The email account that you tried to reach does not exist. Please try double-checking the recipient's email address for typos or unnecessary spaces. Learn more at  https:\/\/support.google.com\/mail\/answer\/6596 190si2150397oie.264 - gsmtp .",
    "TimeStampUtc": 1467143160,
    "Event": {
      "WebHookType": "EmailTrackingAssessment",
      "WebHookTypeId": 3,
      "EventTypeId": 300,
      "EventType": "EmailTrackingAssessmentInvitationBounced",
      "EventTypeLabel": "Assessment invitation bounced"
    }
  },
  {
    "SourceCandidateId": "berke_77b95e58c8904e0bba7c9169190a7b48",
    "Description": "Start Later Link to jeff@berke.as delivered to berke.as mail system. The berke.as mail system replied [250 2.0.0 OK 1467141546 a73si17340871oib.245 - gsmtp .']",
    "EmailAddress": "jeff@berke.as",
    "UserAgent": "",
    "UrlClicked": "",
    "IpAddress": "167.89.43.120",
    "ServerResponse": "250 2.0.0 OK 1467141546 a73si17340871oib.245 - gsmtp .",
    "TimeStampUtc": 1467141546,
    "Event": {
      "WebHookType": "EmailTrackingAssessment",
      "WebHookTypeId": 3,
      "EventTypeId": 312,
      "EventType": "EmailTrackingAssessmentStartLaterDelivered",
      "EventTypeLabel": "Assessment start later link delivered"
    }
  },
  {
    "SourceCandidateId": "berke_77b95e58c8904e0bba7c9169190a7b48",
    "Description": "Assessment Invitation to 'jeff@berke.as' opened in email client [Mozilla\/5.0 (Windows NT 5.1; rv:11.0) Gecko Firefox\/11.0 (via ggpht.com GoogleImageProxy)].",
    "EmailAddress": "jeff@berke.as",
    "UserAgent": "Mozilla\/5.0 (Windows NT 5.1; rv:11.0) Gecko Firefox\/11.0 (via ggpht.com GoogleImageProxy)",
    "UrlClicked": "",
    "IpAddress": "66.249.88.84",
    "ServerResponse": "Smtp Id: ",
    "TimeStampUtc": 1467142645,
    "Event": {
      "WebHookType": "EmailTrackingAssessment",
      "WebHookTypeId": 3,
      "EventTypeId": 303,
      "EventType": "EmailTrackingAssessmentInvitationOpened",
      "EventTypeLabel": "Assessment invitation opened"
    },
  // subsequent messages of same webhook type - always plan for an
  // array of events to be received. we will combine bursts of assessment email tracking
  // events into a single post
]

HTTP Headers

  1. Connection: Keep-Alive
  2. Accept: application/json,application/xml,text/json,text/x-json,text/javascript,text/xml
  3. Accept-Encoding: gzip,deflate
  4. Host: localhost:9090
  5. User-Agent: Berke Assessment Email Tracking Webhook
  6. X-Sha256Digest: 2479e3b83693c97414d713da6e641c9d64cf65b5c99f1a5fde8133988cd62703