{"metadata":{"image":[],"title":"","description":""},"api":{"url":"","auth":"required","settings":"","results":{"codes":[]},"params":[]},"next":{"description":"","pages":[]},"title":"Webhooks","type":"basic","slug":"webhooks_updated","excerpt":"","body":"[block:callout]\n{\n  \"type\": \"info\",\n  \"body\": \"If you are new to webhooks, check out [this comprehensive guide to working with webhooks](https://requestbin.com/blog/working-with-webhooks/#who-supports-webhooks).\",\n  \"title\": \"New to Webhooks?\"\n}\n[/block]\nTo 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\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/32767eb-Webhooks_Settings___Fountain.png\",\n        \"Webhooks_Settings___Fountain.png\",\n        2878,\n        1168,\n        \"#f5f5f5\"\n      ],\n      \"caption\": \"\"\n    }\n  ]\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"title\": \"Webhook Performance and Retries\",\n  \"body\": \"For better webhook performance, we recommend that you **process webhook requests asynchronously**. Not doing so can result in slow or failed webhook responses.\\n\\nFailed 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.\\n\\nWebhooks can be configured and re-enabled from the Company Settings >> Webhooks page in Fountain.\"\n}\n[/block]\n##   Screening Webhooks\n\nWhenever an applicant-related event occurs in Fountain, it can be reported via POST https request to your designated payload URL.\n\nThe following types of events are supported:\n* **Stage Transition**\n   * Applicant lands on \"First Stages\" of the Opening.\n   * Applicant lands on \"Approved Stages\".\n   * Applicant lands on \"Rejected Stages\".\n   * Applicant lands on \"On Hold Stages\".\n   * Applicant lands on \"All Stages\".\n   * Applicant lands on specific stages specified in the settings for \"Selected Stages\".\n* **Background Check Status**\n  * Applicant’s ***Checkr*** background check status has been updated to:\n   * Cleared\n   * Considered\n   * Consider (Engaged)\n   * Consider (Pre-Adverse)\n   * Consider (Post-Adverse)\n   * Suspended\n   * Dispute\n  * Applicant’s ***Onfido*** background check status has been updated to:\n   * Cleared\n   * Consider\n[block:callout]\n{\n  \"type\": \"success\",\n  \"body\": \"Applicant data is transmitted in JSON format with the same structure as API v2 and is nested under applicant key.\",\n  \"title\": \"JSON Format\"\n}\n[/block]\n## Post-Hire Webhooks\n\nWe can also transmit Worker Data when:\n* **Posthire - Worker Deactivated** \n * Worker is marked as \"Deactivate\" in Posthire\n* **Posthire - Worker Activated** \n * Worker is marked as \"Activate\" in Posthire\n* **Posthire - Document Uploaded** \n * Applicant uploads documents during a recurring data collection check. \n* **Posthire - Approve Documents** \n * User approves data or documents collected during a recurring data collection check. \n[block:callout]\n{\n  \"type\": \"success\",\n  \"body\": \"Worker Data is transmitted in JSON format with the same structure as the 'Get Worker Info' API call.\",\n  \"title\": \"JSON Format\"\n}\n[/block]\n**Example:** \n*Applicant Data* \n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"applicant\\\": {\\n    \\\"email\\\": \\\"example:::at:::example.com\\\",\\n    \\\"name\\\": \\\"Logan Paucek\\\",\\n    \\\"first_name\\\": \\\"Logan\\\",\\n    \\\"last_name\\\": \\\"Paucek\\\",\\n    \\\"phone_number\\\": \\\"72 71 98\\\",\\n    \\\"data\\\": {\\n      \\\"city\\\": \\\"Berkeley\\\",\\n      \\\"ssn\\\": \\\"00-22-4566\\\",\\n      \\\"which_bart_stations_are_close_to_you\\\": [\\n        \\\"North Berkeley\\\",\\n        \\\"Downtown Berkeley\\\"\\n      ],\\n      \\\"which_shifts_are_you_available_to_work\\\": [\\n        {\\n          \\\"Monday\\\": \\\"Both\\\"\\n        },\\n        {\\n          \\\"Tuesday\\\": \\\"Both\\\"\\n        },\\n        {\\n          \\\"Wednesday\\\": \\\"Both\\\"\\n        },\\n        {\\n          \\\"Thursday\\\": \\\"Both\\\"\\n        },\\n        {\\n          \\\"Friday\\\": \\\"Both\\\"\\n        },\\n        {\\n          \\\"Saturday\\\": \\\"First\\\"\\n        },\\n        {\\n          \\\"Sunday\\\": \\\"None\\\"\\n        }\\n      ]\\n    },\\n    \\\"created_at\\\": \\\"2017-03-09T10:23:27.596Z\\\",\\n    \\\"receive_automated_emails\\\": true,\\n    \\\"labels\\\": [],\\n    \\\"lessonly\\\": {\\n      \\\"lesson_results\\\": [],\\n      \\\"course_results\\\": []\\n    },\\n    \\\"id\\\": \\\"c780d083-6e73-4810-85a9-17e72d5b7a93\\\",\\n    \\\"background_checks\\\": [],\\n    \\\"funnel\\\": {\\n      \\\"title\\\": \\\"Fountain applicants\\\",\\n      \\\"id\\\": \\\"05e515a8-fe15-4f11-a1a7-98e0aabb0cd6\\\"\\n    },\\n    \\\"stage\\\": {\\n      \\\"title\\\": \\\"Approved\\\",\\n      \\\"id\\\": \\\"e2921e5b-ae20-4c56-9dc8-bb6209e021b7\\\"\\n    },\\n    \\\"document_signatures\\\": [],\\n    \\\"score_cards_results\\\": []\\n  }\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\n*Worker Data* \n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"is_active\\\": true,\\n  \\\"name\\\": \\\"Ms. Isaiah Bernier\\\",\\n  \\\"email\\\": \\\"[email protected]\\\",\\n  \\\"id\\\": \\\"70bbb9f4-bb94-4dbd-a01c-3a2f9ef3098e\\\",\\n  \\\"approved_at\\\": \\\"2018-05-24T03:31:07.626-07:00\\\",\\n  \\\"data_collection_checks\\\": [\\n    {\\n      \\\"id\\\": \\\"a94329ff-47fc-4b9c-8e62-01e0f8e53c91\\\",\\n      \\\"requested_at\\\": \\\"2018-05-14T03:31:08.216-07:00\\\",\\n      \\\"uploaded_at\\\": \\\"2018-05-15T03:31:08.216-07:00\\\",\\n      \\\"rejected_at\\\": \\\"2018-05-16T03:31:08.216-07:00\\\",\\n      \\\"confirmed_at\\\": \\\"2018-05-17T03:31:08.217-07:00\\\",\\n      \\\"canceled_at\\\": \\\"2018-05-19T03:31:08.217-07:00\\\",\\n      \\\"status\\\": \\\"pending\\\",\\n      \\\"confirmed_user\\\": \\\"Rosanna Boehm\\\",\\n      \\\"rule\\\": {\\n        \\\"id\\\": \\\"c5f481e2-519b-4570-8ad0-1ddb30214068\\\",\\n        \\\"title\\\": \\\"Principal Accounts Architect\\\"\\n      },\\n      \\\"uploads\\\": [\\n        {\\n          \\\"created_at\\\": \\\"2018-05-24T03:31:08.504-07:00\\\",\\n          \\\"structured_data\\\": {},\\n          \\\"secure_data\\\": {},\\n          \\\"data\\\": {},\\n          \\\"files\\\": [\\n            {\\n              \\\"name\\\": \\\"global_research_analyst\\\",\\n              \\\"friendly_name\\\": \\\"Global Research Analyst\\\",\\n              \\\"filename\\\": \\\"avatar.jpg\\\",\\n              \\\"size\\\": 99999,\\n              \\\"id\\\": \\\"8ed6f1df-189e-4b81-b2d4-4edee787ec6e/c0ed8226-b812-4ce3-a4da-5e83b8a3731c/e964c508-48a8-4cfc-bfab-bfab8c55df81_avatar.jpg\\\",\\n              \\\"public_url\\\": \\\"https://file.url\\\",\\n              \\\"stage\\\": \\\"\\\"\\n            }\\n          ]\\n        }\\n      ]\\n    }\\n  ]\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Verifying Webhooks (Optional)\"\n}\n[/block]\nTo 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`.\n\nThe 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.\n\nCompare the webhook signature in `X-OBIQ-SIGNATURE-V2` header and the signature you generated to verify if Fountain sent it.\n\n**Example:**\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"def verify_signature(body)\\n  signature = OpenSSL::HMAC.hexdigest(OpenSSL::Digest::SHA256.new, YOUR_API_TOKEN, body)\\n  Rack::Utils.secure_compare(signature, request.headers['X-OBIQ-SIGNATURE-V2'])\\nend\",\n      \"language\": \"text\"\n    }\n  ]\n}\n[/block]\nIf you are whitelisting Fountain's IP addresses, perform the following steps to ensure there will be a smooth transition. \n**(If you currently whitelist our IP address ranges, and fail to add this new IP address, your firewall will block our webhook calls.)**\n\n1. Add the following IP addresses to your allow list: `52.5.72.194`, `52.72.66.54`, `34.198.88.18`\n2. 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.","updates":["60ad5771f3462700304e540b","610bbb297a1ede0035bc9b79"],"order":1,"isReference":false,"hidden":false,"sync_unique":"","link_url":"","link_external":false,"_id":"60087b28e9a6640051e467b2","createdAt":"2021-01-20T18:49:12.434Z","user":"547504ed59fade080004cb8b","category":{"sync":{"isSync":false,"url":""},"pages":[],"title":"Documentation","slug":"documentation","order":0,"from_sync":false,"reference":false,"_id":"59de6011debd1200240f68fb","version":"59de6011debd1200240f68ee","project":"59de6011debd1200240f68ec","__v":0,"createdAt":"2014-11-25T22:41:37.204Z"},"version":{"version":"2.0","version_clean":"2.0.0","codename":"","is_stable":true,"is_beta":false,"is_hidden":false,"is_deprecated":false,"categories":["59de6011debd1200240f68fb","59de6011debd1200240f68fa","59de6011debd1200240f68fc","59de6011debd1200240f68f8","59de6011debd1200240f68f7","59de6011debd1200240f68f9","59de6011debd1200240f68fd","59de6011debd1200240f68fe","59de6011debd1200240f68ff","5a8bfb99f4146e00449cec47","5a8bfcf2e86f530012159bb2","5cd4c29c6ea1040056ec0f55"],"_id":"59de6011debd1200240f68ee","__v":3,"project":"59de6011debd1200240f68ec","createdAt":"2016-06-20T18:15:42.514Z","releaseDate":"2016-06-20T18:15:42.514Z"},"project":"59de6011debd1200240f68ec","__v":2,"parentDoc":null}

Documentation

API Use Cases

Applicant Management

Label Management

Notes Management

Calendar Slot Management

Openings and Stages

Export Management

Posthire Worker Management

Option Bank

Users

Webhooks

[block:callout] { "type": "info", "body": "If you are new to webhooks, check out [this comprehensive guide to working with webhooks](https://requestbin.com/blog/working-with-webhooks/#who-supports-webhooks).", "title": "New to Webhooks?" } [/block] 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 [block:image] { "images": [ { "image": [ "https://files.readme.io/32767eb-Webhooks_Settings___Fountain.png", "Webhooks_Settings___Fountain.png", 2878, 1168, "#f5f5f5" ], "caption": "" } ] } [/block] [block:callout] { "type": "warning", "title": "Webhook Performance and Retries", "body": "For better webhook performance, we recommend that you **process webhook requests asynchronously**. Not doing so can result in slow or failed webhook responses.\n\nFailed 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.\n\nWebhooks can be configured and re-enabled from the Company Settings >> Webhooks page in Fountain." } [/block] ## 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 [block:callout] { "type": "success", "body": "Applicant data is transmitted in JSON format with the same structure as API v2 and is nested under applicant key.", "title": "JSON Format" } [/block] ## 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. [block:callout] { "type": "success", "body": "Worker Data is transmitted in JSON format with the same structure as the 'Get Worker Info' API call.", "title": "JSON Format" } [/block] **Example:** *Applicant Data* [block:code] { "codes": [ { "code": "{\n \"applicant\": {\n \"email\": \"[email protected]\",\n \"name\": \"Logan Paucek\",\n \"first_name\": \"Logan\",\n \"last_name\": \"Paucek\",\n \"phone_number\": \"72 71 98\",\n \"data\": {\n \"city\": \"Berkeley\",\n \"ssn\": \"00-22-4566\",\n \"which_bart_stations_are_close_to_you\": [\n \"North Berkeley\",\n \"Downtown Berkeley\"\n ],\n \"which_shifts_are_you_available_to_work\": [\n {\n \"Monday\": \"Both\"\n },\n {\n \"Tuesday\": \"Both\"\n },\n {\n \"Wednesday\": \"Both\"\n },\n {\n \"Thursday\": \"Both\"\n },\n {\n \"Friday\": \"Both\"\n },\n {\n \"Saturday\": \"First\"\n },\n {\n \"Sunday\": \"None\"\n }\n ]\n },\n \"created_at\": \"2017-03-09T10:23:27.596Z\",\n \"receive_automated_emails\": true,\n \"labels\": [],\n \"lessonly\": {\n \"lesson_results\": [],\n \"course_results\": []\n },\n \"id\": \"c780d083-6e73-4810-85a9-17e72d5b7a93\",\n \"background_checks\": [],\n \"funnel\": {\n \"title\": \"Fountain applicants\",\n \"id\": \"05e515a8-fe15-4f11-a1a7-98e0aabb0cd6\"\n },\n \"stage\": {\n \"title\": \"Approved\",\n \"id\": \"e2921e5b-ae20-4c56-9dc8-bb6209e021b7\"\n },\n \"document_signatures\": [],\n \"score_cards_results\": []\n }\n}", "language": "json" } ] } [/block] *Worker Data* [block:code] { "codes": [ { "code": "{\n \"is_active\": true,\n \"name\": \"Ms. Isaiah Bernier\",\n \"email\": \"[email protected]\",\n \"id\": \"70bbb9f4-bb94-4dbd-a01c-3a2f9ef3098e\",\n \"approved_at\": \"2018-05-24T03:31:07.626-07:00\",\n \"data_collection_checks\": [\n {\n \"id\": \"a94329ff-47fc-4b9c-8e62-01e0f8e53c91\",\n \"requested_at\": \"2018-05-14T03:31:08.216-07:00\",\n \"uploaded_at\": \"2018-05-15T03:31:08.216-07:00\",\n \"rejected_at\": \"2018-05-16T03:31:08.216-07:00\",\n \"confirmed_at\": \"2018-05-17T03:31:08.217-07:00\",\n \"canceled_at\": \"2018-05-19T03:31:08.217-07:00\",\n \"status\": \"pending\",\n \"confirmed_user\": \"Rosanna Boehm\",\n \"rule\": {\n \"id\": \"c5f481e2-519b-4570-8ad0-1ddb30214068\",\n \"title\": \"Principal Accounts Architect\"\n },\n \"uploads\": [\n {\n \"created_at\": \"2018-05-24T03:31:08.504-07:00\",\n \"structured_data\": {},\n \"secure_data\": {},\n \"data\": {},\n \"files\": [\n {\n \"name\": \"global_research_analyst\",\n \"friendly_name\": \"Global Research Analyst\",\n \"filename\": \"avatar.jpg\",\n \"size\": 99999,\n \"id\": \"8ed6f1df-189e-4b81-b2d4-4edee787ec6e/c0ed8226-b812-4ce3-a4da-5e83b8a3731c/e964c508-48a8-4cfc-bfab-bfab8c55df81_avatar.jpg\",\n \"public_url\": \"https://file.url\",\n \"stage\": \"\"\n }\n ]\n }\n ]\n }\n ]\n}", "language": "json" } ] } [/block] [block:api-header] { "type": "basic", "title": "Verifying Webhooks (Optional)" } [/block] 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. Compare the webhook signature in `X-OBIQ-SIGNATURE-V2` header and the signature you generated to verify if Fountain sent it. **Example:** [block:code] { "codes": [ { "code": "def verify_signature(body)\n signature = OpenSSL::HMAC.hexdigest(OpenSSL::Digest::SHA256.new, YOUR_API_TOKEN, body)\n Rack::Utils.secure_compare(signature, request.headers['X-OBIQ-SIGNATURE-V2'])\nend", "language": "text" } ] } [/block] 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.)** 1. Add the following IP addresses to your allow list: `52.5.72.194`, `52.72.66.54`, `34.198.88.18` 2. 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.