Introducing Webhooks and Callbacks support in PHP and Go SDKs

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, PHP and Go 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 SDKs?

APIMatic now supports Webhooks and Callbacks in PHP and Go 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:

PHP

// Create the handler with your shared secret key.
$handler = PaymentHandler::init('hmac-secret-key');

// Verify and parse the request into a typed event.
$result = $handler->verifyAndParse($request);

if ($result instanceof SignatureVerificationFailure) {
    // TODO: add signature verification failure handling
    return response("Received an event with invalid signature: {$result->getErrorMessage()}", 400);
} elseif ($result instanceof VerifiedPaymentEvent) {
    // TODO: add handling logic
    return response("Received an event of type FulfillmentCallback: $result");
} elseif ($result instanceof UnknownEvent) {
    // TODO: add unknown event handling
    return response("Received an unknown event with payload: {$result->getData()}", 400);
}

Go

// Create the handler with your shared secret key.
handler, err := callbacks.PaymentHandler("secret-key")
if err != nil {
    c.JSON(400, map[string]any{"unexpected error": err.Error()})
}

// Verify and parse the request into a typed event.
parsingResult := handler.VerifyAndParseEvent(c.Request)

if event, ok := parsingResult.AsVerifiedPaymentEvent(); ok {
    // TODO: add handling logic
    c.JSON(200, map[string]any{
        "status":    "success",
        "eventInfo": fmt.Sprintf("VerifiedPaymentEvent event received %v", event),
    })
} else if parsingResult.AsUnknownEvent() {
    // TODO: add unknown event handling
    c.JSON(200, map[string]any{
        "status":    "success",
        "eventInfo": "UnknownEvent received",
    })
} else if event, ok := parsingResult.AsSignatureVerificationFailure(); ok {
    // TODO: add signature verification failure handling
    c.JSON(200, map[string]any{
        "status":    "success",
        "eventInfo": fmt.Sprintf("SignatureVerificationFailure event received %v", event),
    })
}

Learn more about webhooks and callbacks