Skip to content
Last updated

import { componentName } from '@redocly/developer-portal/ui'; import { OpenApiTryIt, Alert, ExplainStep, scrollToHeading } from '@redocly/developer-portal/ui';

Quickstart

Prerequisites

Before you begin, make sure you have completed the Getting Started guide — you'll need your CLIENT_ID and CLIENT_SECRET, and a valid access token.

You will also need:

  • A company id.

Step 1

Set up your webhook endpoint.

Create service with a public webhook endpoint.

Show example code (C#)

1. Create a new Web API project

2. Add Azure.Messaging.EventGrid package to project

dotnet add package Azure.Messaging.EventGrid

3. Add ZData.Events.Bank package to project

dotnet add package ZData.Events.Bank

4. Create Webhook controller

C#

using Azure.Messaging.EventGrid;
using Azure.Messaging.EventGrid.SystemEvents;
using Microsoft.AspNetCore.Mvc;
using ZData.Events.Bank;

namespace WebhookTest.Controllers
{
    [ApiController]
    [Route("webhooks")]
    public class WebhookController : ControllerBase
    {
        private readonly ILogger\<WebhookController> logger;

        public WebhookController(ILogger\<WebhookController> logger)
        {
            this.logger = logger;
        }

        [HttpPost("events")]
        public IActionResult HandleEvents(EventGridEvent[] events)
        {
            foreach (EventGridEvent eventGridEvent in events)
            {
                // Handle system events
                if (eventGridEvent.TryGetSystemEventData(out object eventData))
                {
                    // Handle the subscription validation event
                    if (eventData is SubscriptionValidationEventData subscriptionValidationEventData)
                    {
                        var responseData = new SubscriptionValidationResponse()
                        {
                            ValidationResponse = subscriptionValidationEventData.ValidationCode
                        };
                        return Ok(responseData);
                    }
                }

                // 2. Check if event is an Aritma (ZData) event.
                if (eventGridEvent.EventType == typeof(SettlementReceived).FullName)
                {
                    var settlementReceivedEvent = eventGridEvent.Data.ToObjectFromJson\<SettlementReceived>();

                    // TODO: handle the event:
                    logger.LogInformation(settlementReceivedEvent.BatchId.ToString());
                }
            }
            return BadRequest();
        }
    }
}

Step 2

Create a new Event Subscription.

<OpenApiTryIt definitionId="bankservice" operationId="CreateEventGridSubscription" id="step-1" properties={{ eventTypes: [ "ZData.Events.Bank.StatementsReceived", "ZData.Events.Bank.SettlementReceived" ], destination: { endpointUrl: "https://your_webhook_url.com", maxEventsPerBatch: 10, preferredBatchSizeInKilobytes: 64, azureActiveDirectoryApplicationIdOrUri: null, azureActiveDirectoryTenantId: null } }} parameters={{ path: { companyId: "00000000-0000-0000-0000-000000000000", subscriptionName: "YourSubscriptionName" } }} securityDefaults={{ oauth2: { client_id: 'YOUR_CLIENT_ID', client_secret: 'YOUR_CLIENT_SECRET', scopes: 'bankservice' } }} onResponse={({ response }) => { if (response.ok) { scrollTo(0, document.querySelector('#step-2').offsetTop - 20, { behavior: 'smooth' }) } }} />

Step 3

GET the status of your Event Subscription.

<OpenApiTryIt definitionId="bankservice" operationId="GetEventSubscription" id="step-2" needs={['step-1']} properties={{}} parameters={(step1) => ({ path: { companyId: step1.response.body.CompanyId, subscriptionName: step1.response.body.SubscriptionName } })} placeholder={(step1) => { if (!step1) { return ( Please complete Step 2 first. ); } }} securityDefaults={(step1) => console.log(step1)} />