Skip to main content

Webhooks

JOFI supports sending events to a webhook endpoint that you provide. If you'd like to explore a few popular examples of this approach, browse the webhook docs for Stripe, Github, and Twilio SendGrid.

For a list of the JOFI events that trigger webhook requests, see Events.

How it works​

JOFI will send events to your webhook endpoint as participants progress through the process. Create your webhook endpoint and provide it to your JOFI representative, and they will configure your Account to begin calling your webhook endpoint when events occur within JOFI.

You do not have to use webhook endpoints and events. If you prefer, your system can make a GET request any time you need to fetch the most up-to-date data for any resource. However, using webhook endpoints and events will allow your system to immediately react and take action when events occur within JOFI.

For example, if you would like to send an email notification to your user when a JOFI participant completes an assessment, or if you want to display the assessment statuses for your participants within your system. The webhook endpoints and events are a perfect use case for those scenarios, because JOFI will call your webhook endpoint when the participant completes an assessment and your webhook handler can decide what to do, such as send the email notification and update the assessment status in your database.

Webhook Verification​

Webhook verification confirms that a webhook request genuinely comes from the expected sender (like JOFI) and hasn't been tampered with. It prevents unauthorized systems from impersonating the sender and ensures the message's integrity.

JOFI currently supports 2 options for webhook verification: HMAC and Basic Auth. OAuth / JWT support is coming soon!

  1. HMAC: A shared secret is used to generate a unique signature of the webhook payload. The receiver recalculates the signature and compares it to the one sent, ensuring authenticity and integrity. For reference, this method is offered by Stripe, Github, Twilio SendGrid, and Dosusign.
  2. OAuth Client Credentials / Access Token: You provide JOFI with a client ID, client secret, and a URL for your authorization sever. When JOFI is preparing to send an event to your webhook endpoint, JOFI will first call your authorization server and will provide the client ID and client secret. Your auth server wil return an access token. JOFI includes the access token in an Authorization header when it makes the POST request to your webhook endpoint. Your system validates the token before handling the event to verify that the request came from JOFI. Learn more here. For reference, this method is offered by Twilio SendGrid and Docusign. (coming soon!)
  3. Basic Auth: Username and password (Base64 encoded) are sent in the webhook request headers. The receiver verifies these credentials. For reference, this method is offered by Docusign.

Example​

  • You create a webhook endpoint like: https://www.your-example-domain-90bf2a.com/webhooks/incoming/jofi
  • You share the webhook endpoint with your JOFI representative and indicate you would like to use Basic Auth
  • You securely provide your Basic Auth username and password
  • Your JOFI rep creates the webhook and stores your username and password (encrypted at rest)
  • When events occur in JOFI, JOFI will make a POST request to your webhook endpoint with event payload and an Authorization header
  • Your system verifies the username and password in the Authorization header, and then uses the event payload to update your record for the participant or take some action like sending a notification