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.
Live vs test webhook URLs
Your account can have two webhook endpoints:
| Endpoint | Purpose |
|---|---|
| Live webhook | Receives automatic event delivery when participants progress in production (for example, invitation.accepted, test_taker.assessment_completed) |
| Test webhook | Optional URL for integration testing. JOFI does not send automatic events here. Request a JOFI Admin to send test events to this endpoint; end users cannot trigger test deliveries themselves |
Automatic event delivery uses your live webhook URL only. Test API keys (sk_test_...) do not create records and do not trigger the event pipeline, so they will not send events to either URL.
Work with your JOFI representative to configure both endpoints. Webhook URLs must use HTTPS.
How it works
JOFI sends events to your live 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 live webhook 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 supports three options for webhook verification:
- 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 Docusign.
- OAuth Client Credentials / Access Token: You provide JOFI with a client ID, client secret, and a URL for your authorization server. When JOFI is preparing to send an event to your webhook endpoint, JOFI will first call your authorization server with the client ID and client secret. Your auth server returns 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. Learn more here. Contact your JOFI representative to enable this method.
- 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 live webhook endpoint with the event payload and an Authorization header
- Your system verifies the credentials, then uses the event payload to update your record for the participant or take some action like sending a notification