Learn how to register your application to receive and verify webhook notifications from Teller and be notified of events not represented in the Teller API itself
Teller can send you webhook events related to your application and its enrollments, e.g. when an enrollment is disconnected and the user should reconnect using Teller Connect, Teller will send you a webhook event of type
enrollment.disconnected and your application can take appropriate action.
To register a new webhook, you need to have a URL in your app that Teller can call. You can configure a new webhook from the Teller Dashboard under Application Settings.
Now, whenever something of interest happens in your app, a webhook is fired off by Teller. In the next section, we'll look at how to consume webhooks.
When your app receives a webhook request from Teller, check the
type attribute to see what event caused it. The first part of the event type categorizes the payload type, e.g.,
Example webhook payload
In the example above, an enrollment has entered a disconnected state because the financial institution has completely locked the account. This may happen for legal reasons, because an account has been involved in fraud, or an attacker has repeatedly tried to login by guessing the end user's credentials.
The webhook object has the following shape
The id of the webhook event
Event specific data
The ISO 8601 timestamp of the event.
The type of the event, e.g
The shape of the
payload depends on the event's
This event is fired when enrollment connectivity is lost and cannot be restored without the end-user.
The id of the affected enrollment
The reason the enrollment was disconnected. Possible values:
This is a test event triggered from the Application Settings page. Use this to test your webhook implementation.
The test event does not have any payload content
Teller signs every webhook event with all non-expired signing secrets, that only you and Teller know. You can get your signing secrets from the Application Settings page.
Teller sends a signature in the Teller-Signature HTTP header:
Most of the time there will be only one non-expired signing secret, so the signature header will look like this:
To verify that the payload was created by Teller, you have to calculate the signature and it must be equal to the signature extracted from the signature header.
To calculate the signature:
signature_timestampand the request's JSON body with a . character
- Compute HMAC with SHA-256 using the non-expired signing secret as the key and
signed_messageas the message
To prevent replay attacks you should reject webhook events with a
signature_timestamp (Unix time) older than 3 minutes.
When you have a policy to periodically roll secrets, Teller allows you to do it without a gap in signature verification.
To expire the current signing secret, go to the Application Settings page and select when the secret should expire, e.g. in 2 hours. When you press Save, Teller will create a new non-expired secret, and from that moment, Teller will sign all webhook events with both secrets until the old secret expires:
This gives you time to update your application with the new secret.