Introduction

Webhooks are a powerful way to receive real-time updates from Fiskil directly to your application. Rather than constantly polling Fiskil's API, webhooks allow Fiskil to push notifications to your app whenever specific events occur. This not only optimizes performance but also ensures that your app reacts immediately to critical updates like new user consents or fresh banking transactions.

Fiskil sends these notifications over HTTPS in a structured JSON format, making it easy to integrate and automate responses in your backend systems. Whether you're handling financial transactions, energy data, or user consents, webhooks streamline your workflows with up-to-the-minute accuracy.

Why Use Webhooks?

• Real-Time Updates: Get notified instantly when important events occur, reducing the need for frequent API polling.
• Automated Workflows: Trigger backend processes like updating account balances or alerting users as soon as new data is available.
• Resource Efficient: Save bandwidth and server resources by receiving data only when it changes.

Common Use Cases

• User Consent Notifications: Receive alerts when an end user consents to share their data (consent.received), enabling immediate onboarding or data access.
• Transaction Updates: Get notified when new transactions are available (banking.transactions.sync.completed), allowing your app to update balances or generate spending reports.
• Energy Data Syncs: Automatically update your system with the latest energy usage or billing data, keeping your dashboards current.

Webhook Setup

Step 1: Create Your Webhook Endpoint

Before Fiskil can send you notifications, you need to set up an endpoint to receive them. Here's how:

Create an HTTP/HTTPS Endpoint:

• Build a URL on your server that can accept POST requests.
• Ensure this endpoint is publicly accessible.
• For production, HTTPS is mandatory to secure data in transit.

Handle Incoming JSON Payloads:

• Your endpoint should parse and handle JSON payloads.
• Use the event data to trigger actions within your application.

Verify Payload Authenticity:

• Fiskil includes an HMAC SHA256 signature in the X-Fiskil-Signature header.
• You'll verify this signature using a secret key provided during webhook registration (details in the Security section).

Step 2: Register Your Webhook in Fiskil

Access the Fiskil Console:

• Log in with an account that has Owner or Developer access.

Navigate to Webhooks:

• Go to Settings > Teams > Webhooks.

Register Your Endpoint:

• Enter your endpoint URL.
• Select the events you want to subscribe to (e.g., banking.transactions.sync.completed).
• Note: You can modify the endpoint URL later, but event subscriptions cannot be changed once created.

Save Your Webhook:

• After registration, Fiskil will start sending events to your endpoint as they occur.

Event Types

Consent Events

• consent.received: Triggered when an end user grants data-sharing consent.
• consent.updated: Triggered when an end user modifies their consent.
• consent.revoked: Triggered when consent expires or is revoked.

Identity Sync Events

• common.identity.sync.completed: Indicates successful syncing of an end user's identity data.

Customer Data Sync Events

Triggered when end-user data is cached or updated in Fiskil's platform.

Energy Industry

• energy.billing.sync.completed: Billing data synced.
• energy.usage.sync.completed: Usage data synced.
• energy.servicepoints.sync.completed: Service point data synced.
• energy.accounts.sync.completed: Account data synced.
• energy.concessions.sync.completed: Concession data synced.
• energy.der.sync.completed: Distributed Energy Resource data synced.
• energy.invoices.sync.completed: Invoices synced.
• energy.paymentschedules.sync.completed: Payment schedules synced.
• energy.plans.sync.completed: Energy plans synced.

Banking Industry

• banking.accounts.sync.completed: Banking account data synced.
• banking.balances.sync.completed: Balance data synced.
• banking.transactions.basic.sync.completed: Basic transaction data synced.
• banking.transactions.sync.completed: Detailed transactions synced (including metadata).
• banking.payees.sync.completed: Payees synced.
• banking.directdebits.sync.completed: Direct debits synced.
• banking.scheduledpayments.sync.completed: Scheduled payments synced.
• banking.products.sync.completed: Banking product data synced.

Delivery & Payload Structure

Payload Format

Fiskil delivers webhook payloads in JSON format with the following structure:

{
  "publish_time": "2023-11-24T05:10:03.957Z",
  "message_id": "9061924608716421",
  "data": {
    "consent_id": "1a460c22-c3ca-4901-8269-0b65c155b483",
    "client_id": "2XbIEYCqr3rBLrjPNGmxuB5rqwy",
    "end_user_id": "2XpN1YbKmoFcqbcN1Ji58kWyv3e",
    "event": "energy.accounts.sync.completed",
    "institution_id": "1",
    "account_ids": ["262c6cc1-1b35-4f3f-b3d0-98976a86c6ee"], 
  }
}

Payload Fields

• publish_time: Timestamp of the event (RFC3339 format).
• message_id: Unique identifier for the event (useful for deduplication).
• data: Contains event-specific data, including:
  • event: Type of event triggered.
  • end_user_id: Unique ID of the end user.
  • client_id: Your app's unique identifier.
  • institution_id: The data holder's ID.
  • consent_id: The ID of the user's consent.
  • account_ids: the list of accounts related to synced data. It is only available for *.accounts.sync.completed and *.balances.sync.completed events.
  • payee_ids: the list of payees related to synced data. It is only available for banking.payees.sync.completed event.

Retry Logic

If Fiskil cannot deliver an event (e.g., server unreachable or non-2xx response), it retries up to 5 times with backoff intervals between 1 to 10 minutes. After exhausting retries, the event is discarded.

Security

HTTPS Enforcement

For secure data transmission, Fiskil enforces HTTPS on all webhook endpoints in production.

Verifying Webhook Signatures

Fiskil includes an HMAC SHA256 signature in the X-Fiskil-Signature header. This ensures that the event comes from Fiskil and hasn't been tampered with.

Verifying Signatures in Go

Here's how to verify the signature using Go:

package main
 
import (
  "crypto/hmac"
  "crypto/sha256"
  "encoding/base64"
  "fmt"
)
 
func main() {
  var payloadData = `{"publish_time":"2023-11-23T03:03:30.792Z","message_id":"9790112556309026","data":{"arrangementId":"4a726862-6b39-4cd5-92c0-3d20fe96a202","clientId":"2XbIYazvJeBwaJx1xCaFar64uVk","endUserId":"2YPr9YiWLNj3KZt9ycjbvy4bRx5","institutionId":"1"}}`
  var signingSecret = "jf+cnWPind3y0kYqJM4cPAC/8kNcwVXE8/fKs/Kz/SxXIkhVfvV8yh8dtEX9+K2PsmItKu5Jqqwy7cw2JQ+ozsSo2M9qmwpPxRMCREO+"
 
  secretBytes, err := base64.StdEncoding.DecodeString(signingSecret)
  if err != nil {
    panic(err)
  }
 
  hmac := hmac.New(sha256.New, secretBytes)
  hmac.Write([]byte(payloadData))
 
  signature := base64.StdEncoding.EncodeToString(hmac.Sum(nil))
  fmt.Println(signature) // Compare this with X-Fiskil-Signature header
}

Verifying with OpenSSL

# Base64 decode the signing secret
$ echo 'jf+cnWPind3y0kYqJM4cPAC/8kNcwVXE8/fKs/Kz/SxXIkhVfvV8yh8dtEX9+K2PsmItKu5Jqqwy7cw2JQ+ozsSo2M9qmwpPxRMCREO+' | base64 -d > secret.key
 
# Generate the HMAC signature
$ cat data.json | tr -d '\n' | openssl dgst -sha256 -mac HMAC -macopt key:secret.key
 
# Compare the output to the X-Fiskil-Signature header value

By verifying signatures, you ensure that only legitimate events from Fiskil are processed by your application.

Conclusion

With Fiskil webhooks, you can build responsive, data-driven applications that react to real-time financial and energy data. By following this guide, you'll be able to securely set up, manage, and verify webhooks to streamline your workflows and deliver timely updates to your users.

For additional help or troubleshooting, refer to our API documentation or contact support.