Introducing Webhooks and Callbacks support in SDKs and Developer Portals

This enhancement allows developers to easily manage API notifications and event-driven workflows without extra setup. With type-safe handlers and configured signature verification, integration becomes simpler and more reliable.

Details

Webhooks and callbacks are widely used in APIs to deliver information asynchronously, notifying clients about events or providing results after a request has been initiated. Without SDK support, developers often need to write custom code for parsing payloads, verifying signatures, and mapping data. With this enhancement, all mentioned SDKs automatically generate type-safe handlers and utilities, giving developers a consistent and reliable way to work with event-driven APIs.

What's New in Developer Portal?

Callback Associated in API Endpoints: Each API endpoint page now includes a collapsible accordion listing all associated callbacks, making it easier to explore callback details without leaving the endpoint view.

Improved Documentation: Clearer descriptions and usage guidelines for callbacks and webhooks are now available, ensuring developers can integrate with confidence.

Ready to Use Examples: Updated code snippets in multiple languages demonstrate how to handle webhook payloads, making it faster to test and implement integrations.

Webhook

Callback

What’s New in SDKs?

APIMatic now supports Webhooks and Callbacks in C#, Java, Python, Ruby and TypeScript SDKs.

• Type Safe Webhook Handlers
• Type Safe Callback Handlers
• HMAC Signature Verification

Usage Example

Developers can now verify signatures and handle webhook events with type-safe parsing:

.NET

// Create the HttpRequestData from the incoming HttpRequest
var eventRequest = HttpRequestData.FromAspNetCoreParams(
  Request.Method,
  Request.Scheme,
  Request.Host.ToString(),
  Request.Path.ToString(),
  Request.QueryString.ToString(),
  Request.Headers,
  Request.Body,
  Request.Query,
  Request.Cookies,
  Request.Protocol,
  Request.ContentType,
  Request.ContentLength
);

// Use the provided handler to verify and parse the incoming event
var handler = new PaymentHandler("hmac-secret-key");

var eventParsingResult = await handler.VerifyAndParseEventAsync(eventRequest);
var result = eventParsingResult.MatchSome<string>(
  verifiedPaymentEvent: payment => $"Payment verification received {payment}",
  signatureVerificationFailed: error => $"Signature verification failed {error}",
  unknown: () => "Unknown event received"
);

Java

// Create the HttpRequest from the incoming Request
HttpRequest httpRequest = HttpRequest.fromHttpServletRequest(
  Collections.list(request.getHeaderNames()).stream().collect(Collectors.toMap(
    h -> h,
    h -> Collections.list(request.getHeaders(h))
  )),
  request.getParameterMap(),
  request.getRequestURL(),
  request.getQueryString(),
  request.getMethod(),
  body
);

// Use the provided handler to verify and parse the incoming event
PaymentHandler handler = new PaymentHandler("hmac-secret-key");

String result = handler.verifyAndParseEventAsync(httpRequest).thenApply(paymentParsingResult ->
  paymentParsingResult.matchSome(new PaymentParsingResult.SomeCases<String>() {
    @Override
    public String verifiedPaymentEvent(VerifiedPaymentEvent verifiedPaymentEvent) {
      // TODO: add handling logic
      return "VerifiedPaymentEvent event received " + verifiedPaymentEvent;
    }

    @Override
    public String unknown() {
      // TODO: add unknown event handling
      return "Unknown event received";
    }

    @Override
    public String signatureVerificationFailed(SignatureVerificationResult signatureVerificationResult) {
      // TODO: add signature verification failure handling
      return "SignatureVerificationResult event received " + signatureVerificationResult;
    }
  })
).join();

Python

# Create the handler with your shared secret key.
handler = PaymentHandler(secret_key="hmac-secret-key")

# Convert the incoming request using to_core_request (Django/Flask)
# or await to_core_request_async (FastAPI).
core_req = to_core_request(request)

# Verify and parse the request into a typed event.
event = handler.verify_and_parse_event(core_req)

# Pattern match on the event types and handle it.
if isinstance(event, VerifiedPaymentEvent):
  print("Payment verification received")
  # TODO: add handling logic
elif isinstance(event, SignatureVerificationFailure):
  print("Signature verification failed")
  # TODO: add signature verification failure handling
elif isinstance(event, UnknownEvent):
  print("Unknown event")
  # TODO: add unknown event handling

Ruby

# Create the handler using your shared secret key.
handler = PaymentHandler.new('your-shared-secret')

# Verify and parse the request (Rack::Request compatible) into a typed event.
event = handler.verify_and_parse_event(request)

# Pattern match on the event types and handle it.
case event
when VerifiedPaymentEvent
  puts 'Payment verification received'
  # TODO: Add handling logic
when SignatureVerificationFailure
  puts 'Signature verification failed'
  # TODO: Add failure handling
when UnknownEvent
  puts 'Unknown event received'
  # TODO: Add unknown-event handling
else
  # TODO: Add default handling
end

TypeScript

// Create the handler with your shared secret key.
const handler = new PaymentHandler('hmac-secret-key');

// Convert the incoming request.
const coreRequest = convertExpressRequest(request);

// Verify and parse the request into a typed event.
const result = handler.verifyAndParseEvent(coreRequest);

if (PaymentParsingResult.isVerifiedPaymentEvent(result)) {
  // Result narrowed down to type VerifiedPayment event.
  return result;
} else if (PaymentParsingResult.isEventTypeUnknown(result)) {
  // Result narrowed down to type UnknownEvent.
  return result;
} else if (PaymentParsingResult.isSignatureVerificationFailure(result)) {
  // Result narrowed down to type SignatureVerificationFailure.
  return result;
}

Learn more about webhooks and callbacks