New to Webhooks?
If you are new to webhooks, check out this comprehensive guide to working with webhooks.
To add and manage webhooks, navigate to your Profile → Company Settings → Webhooks (under Developer Settings) or you can go directly to the page by updating this direct URL with your account's name: https://www.fountain.com/[COMPANY_NAME]/webhooks/settings
Webhook Performance and Retries
For better webhook performance, we recommend that you process webhook requests asynchronously. Not doing so can result in slow or failed webhook responses.
Failed webhook requests will be retried 2 times after the initial request fails. If one of your webhooks consistently fails more than 10 times in a 24 hour period, we will disable it and notify you that your webhook settings need to be changed before reactivating it.
Webhooks can be configured and re-enabled from the Company Settings >> Webhooks page in Fountain.
Screening Webhooks
Whenever an applicant-related event occurs in Fountain, it can be reported via POST https request to your designated payload URL.
The following types of events are supported:
- Stage Transition
- Applicant lands on "First Stages" of the Opening.
- Applicant lands on "Approved Stages".
- Applicant lands on "Rejected Stages".
- Applicant lands on "On Hold Stages".
- Applicant lands on "All Stages".
- Applicant lands on specific stages specified in the settings for "Selected Stages".
- Background Check Status
- Applicant’s Checkr background check status has been updated to:
- Cleared
- Considered
- Consider (Engaged)
- Consider (Pre-Adverse)
- Consider (Post-Adverse)
- Suspended
- Dispute
- Applicant’s Onfido background check status has been updated to:
- Cleared
- Consider
JSON Format
Applicant data is transmitted in JSON format with the same structure as API v2 and is nested under applicant key.
Post-Hire Webhooks
We can also transmit Worker Data when:
- Posthire - Worker Deactivated
- Worker is marked as "Deactivate" in Posthire
- Posthire - Worker Activated
- Worker is marked as "Activate" in Posthire
- Posthire - Document Uploaded
- Applicant uploads documents during a recurring data collection check.
- Posthire - Approve Documents
- User approves data or documents collected during a recurring data collection check.
JSON Format
Worker Data is transmitted in JSON format with the same structure as the 'Get Worker Info' API call.
Example:
Applicant Data
{
"applicant": {
"email": "[email protected]",
"name": "Logan Paucek",
"first_name": "Logan",
"last_name": "Paucek",
"phone_number": "72 71 98",
"data": {
"city": "Berkeley",
"ssn": "00-22-4566",
"which_bart_stations_are_close_to_you": [
"North Berkeley",
"Downtown Berkeley"
],
"which_shifts_are_you_available_to_work": [
{
"Monday": "Both"
},
{
"Tuesday": "Both"
},
{
"Wednesday": "Both"
},
{
"Thursday": "Both"
},
{
"Friday": "Both"
},
{
"Saturday": "First"
},
{
"Sunday": "None"
}
]
},
"created_at": "2017-03-09T10:23:27.596Z",
"receive_automated_emails": true,
"labels": [],
"lessonly": {
"lesson_results": [],
"course_results": []
},
"id": "c780d083-6e73-4810-85a9-17e72d5b7a93",
"background_checks": [],
"funnel": {
"title": "Fountain applicants",
"id": "05e515a8-fe15-4f11-a1a7-98e0aabb0cd6"
},
"stage": {
"title": "Approved",
"id": "e2921e5b-ae20-4c56-9dc8-bb6209e021b7"
},
"document_signatures": [],
"score_cards_results": []
}
}
Worker Data
{
"is_active": true,
"name": "Ms. Isaiah Bernier",
"email": "[email protected]",
"id": "70bbb9f4-bb94-4dbd-a01c-3a2f9ef3098e",
"approved_at": "2018-05-24T03:31:07.626-07:00",
"data_collection_checks": [
{
"id": "a94329ff-47fc-4b9c-8e62-01e0f8e53c91",
"requested_at": "2018-05-14T03:31:08.216-07:00",
"uploaded_at": "2018-05-15T03:31:08.216-07:00",
"rejected_at": "2018-05-16T03:31:08.216-07:00",
"confirmed_at": "2018-05-17T03:31:08.217-07:00",
"canceled_at": "2018-05-19T03:31:08.217-07:00",
"status": "pending",
"confirmed_user": "Rosanna Boehm",
"rule": {
"id": "c5f481e2-519b-4570-8ad0-1ddb30214068",
"title": "Principal Accounts Architect"
},
"uploads": [
{
"created_at": "2018-05-24T03:31:08.504-07:00",
"structured_data": {},
"secure_data": {},
"data": {},
"files": [
{
"name": "global_research_analyst",
"friendly_name": "Global Research Analyst",
"filename": "avatar.jpg",
"size": 99999,
"id": "8ed6f1df-189e-4b81-b2d4-4edee787ec6e/c0ed8226-b812-4ce3-a4da-5e83b8a3731c/e964c508-48a8-4cfc-bfab-bfab8c55df81_avatar.jpg",
"public_url": "https://file.url",
"stage": ""
}
]
}
]
}
]
}
Verifying Webhooks (Optional)
To verify that a webhook was actually sent by Fountain, every payload is signed with a signature that is passed through the header X-OBIQ-SIGNATURE-V2.
The signature is Hex encoded and can be replicated by applying HMAC-SHA-256 to the webhook's request body using your Fountain Private API token as a secret. This API token can be found on your API settings.
Note: It is possible to change request body to applicant ID via Admin Tools. Please follow up with Fountain if you are interested in this. If generating Check Signature from Body leads to a mismatch please try generating Check Signature from applicant ID.
Compare the webhook signature in X-OBIQ-SIGNATURE-V2 header and the signature you generated to verify if Fountain sent it.
Example:
def verify_signature(body)
signature = OpenSSL::HMAC.hexdigest(OpenSSL::Digest::SHA256.new, YOUR_API_TOKEN, body)
Rack::Utils.secure_compare(signature, request.headers['X-OBIQ-SIGNATURE-V2'])
end
If you are whitelisting Fountain's IP addresses, perform the following steps to ensure there will be a smooth transition.
(If you currently whitelist our IP address ranges, and fail to add this new IP address, your firewall will block our webhook calls.)
- Add the following IP addresses to your allow list:
52.5.72.194,52.72.66.54,34.198.88.18 - If you were already using our IP ranges, you need to add this to the static IP address. The previous range will not work anymore.