Teller

Signature Verification

Property	Value
Algorithm	HMAC-SHA256
Header	`Teller-Signature`
Format	`t=signature_timestamp,v1=signature`
Timestamp tolerance	180 seconds (3 minutes)

Signing formula:

HMAC-SHA256("signature_timestamp.body", signing_secret)

Transyt parses the Teller-Signature header, extracts the t (timestamp) and v1 (signature) values, then computes the expected signature using the stored signing secret. The timestamp is validated to be within 3 minutes of the current time to prevent replay attacks.

Multiple Signatures

During secret rotation, Teller signs events with all non-expired secrets. The header may contain multiple v1 values:

Teller-Signature: t=signature_timestamp,v1=signature_with_new_secret,v1=signature_with_old_secret

Transyt validates against each v1 signature and accepts the event if any one matches.

Setup in Teller Dashboard

Go to Application Settings in the Teller Dashboard

https://ingest.transyt.com/teller/{your-account-slug}

Copy the Signing secret from the Application Settings page
Use the Test webhook button to send a webhook.test event and verify connectivity

Account Configuration

curl -X POST https://ingest.transyt.com/admin/accounts \
  -H "X-Admin-Token: YOUR_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "teller",
    "account_slug": "my-app",
    "app_key": "my-app",
    "signing_secret_current": "your-teller-signing-secret"
  }'

Event Types

Teller Event	Description
`enrollment.disconnected`	Enrollment connection to the institution is irrecoverably broken
`transactions.processed`	New transactions found and categorized after polling
`account.number_verification.processed`	Microdeposit account verification completed or expired
`webhook.test`	Test event triggered from the Teller Dashboard

Enrollment Disconnected Reasons

When type is enrollment.disconnected, the payload includes a reason field:

Reason	Description
`disconnected`	Generic disconnection
`disconnected.account_locked`	Institution locked the account
`disconnected.credentials_invalid`	User credentials are no longer valid
`disconnected.enrollment_inactive`	Enrollment has become inactive
`disconnected.user_action.captcha_required`	User needs to complete a captcha
`disconnected.user_action.contact_information_required`	User needs to update contact info
`disconnected.user_action.insufficient_permissions`	Insufficient permissions
`disconnected.user_action.mfa_required`	User needs to complete MFA
`disconnected.user_action.web_login_required`	User needs to log in via web

Account Verification Statuses

When type is account.number_verification.processed, the payload includes a status field: completed or expired.

Webhook Payload

{
  "id": "wh_oiffb5cocakqmksbkg000",
  "payload": {
    "enrollment_id": "enr_oiffb5cocakqmksbkg001",
    "reason": "disconnected.account_locked"
  },
  "timestamp": "2023-07-10T03:49:29Z",
  "type": "enrollment.disconnected"
}

External ID

The webhook event id field (e.g., wh_oiffb5cocakqmksbkg000) is used as the external ID for deduplication.

Polling Behavior

Teller polls connected financial institutions multiple times per day on a non-predictable schedule, with at least one polling attempt every 24 hours. The transactions.processed webhook fires when new transactions are found during these polls. If connectivity to an enrollment is temporarily lost, no transactions.processed events are sent until connectivity is restored.