Webhooks
You can configure Userfront to make a callback request to your server each time a user or tenant is created, updated, or deleted. These requests are called webhooks(opens new window), and they contain information about the user or tenant that changed.
Userfront webhooks are made via POST request and include an API key in the header that your server can use to verify that the request came from Userfront.
#Authentication
Userfront includes an API key in the header of each webhook that you can use to authenticate the request. You can view your Webhook API keys in the Userfront Dashboard.
Do not share your Webhook API keys in publicly accessible areas such as GitHub, client-side code, and so forth.
Webhook API keys are included as HTTP Bearer Auth(opens new window) tokens, included in the header of each request as:
Authorization: Bearer your_webhook_api_key.
All live webhooks must be made over HTTPS. Webhooks configured for plain HTTP will fail.
Each webhook will have an authorization header containing your workspace's webhook API key.
Your server should read this header and verify that it matches the webhook API key found in your dashboard.
#Users
Users are the user records within your workspace or within your workspace's tenants.
There are webhooks available for user creation, update, and deletion.
#User created
This webhook is sent whenever a new user is created.
#User updated
This webhook is sent whenever an existing user is updated.
#User deleted
This webhook is sent whenever a user is deleted.
#Tenants
Tenants allow you to sub-divide your application so that certain users only have access to certain parts.
There are webhooks available for tenant creation, update, and deletion.
#Tenant created
This webhook is sent whenever a new tenant is created.
#Tenant updated
This webhook is sent whenever an existing tenant is updated.
#Tenant deleted
This webhook is sent whenever a tenant is deleted.
#User sign-on via email and SMS
By default, when you have enabled login links via email or verification codes via email or SMS text message as sign-on options for your tenant, Userfront sends these emails and SMS messages on your behalf.
You may set webhooks to handle these requests for your tenant. If you have set a webhook, Userfront will call it rather than sending an email or SMS message. This lets you control how emails and SMS messages are sent.
If you set a webhook, you are responsible for sending the login link or verification code to the user - if a webhook is set for a login method, Userfront will not send the email or SMS message for that method.
If you have a webhook set, you can clear the webhook to resume the default behavior and have Userfront send the email or SMS messages on your behalf.
Send login link by email
Send verification code by email
Send verification code by SMS
#Send login link by email
This webhook is called when a user requests a login link to be sent to them via email.
When using this webhook, you should send the provided login link to the user via your own system. The user will then use the link to complete the sign-on process.
Payload parameters
The type of action: "login"
The model name: "user"
Whether the action was performed in test mode or live mode.
Information about the authentication factor, including the link URL and message.
The authentication strategy: "link"
The authentication channel: "email"
The user's email address. You should send the link to this address.
The link URL that the user should follow to complete their sign-on. You should include this in the email to the user.
The single-use token that is included in the login link URL.
The user's UUID, included in the login link URL.
A suggested full message to send which includes the tenant's name and the login link URL.
Expiration timestamp for the login link URL.
Information about the tenant and user for this sign-on request.
#Send verification code by email
This webhook is called when a user requests a verification code to be sent to them via email.
When using this webhook, you should send the provided verification code to the user via your own system. The user will then use the verification code to complete the sign-on process.
Payload parameters
The type of action: "login"
The model name: "user"
Whether the action was performed in test mode or live mode.
Information about the authentication factor, including the verification code and message.
The authentication strategy: "verificationCode"
The authentication channel: "email"
The user's email address. You should send the verification code to this address.
The verification code that the user should enter to complete their sign-on. You should include this in the email to the user.
A suggested full message to send which includes the tenant's name and the verification code.
Expiration timestamp for the verification code.
Information about the tenant and user for this sign-on request.
#Send verification code by SMS text message
This webhook is called when a user requests a verification code to be sent to them via SMS text message.
When using this webhook, you should send the provided verification code to the user via your own system. The user will then use the verification code to complete the sign-on process.
Payload parameters
The type of action: "login"
The model name: "user"
Whether the action was performed in test mode or live mode.
Information about the authentication factor, including the verification code and message.
The authentication strategy: "verificationCode"
The authentication channel: "sms"
The user's phone number. You should send the verification code to this phone number.
The verification code that the user should enter to complete their sign-on. You should include this in the message to the user.
A suggested full message to send which includes the tenant's name and the verification code.
Expiration timestamp for the verification code.
Information about the tenant and user for this sign-on request.