Leverage webhooks

Webhooks are a form of server-to-server communication that sends notifications as soon as specific events occur. By subscribing to webhooks, you can reduce the number of API calls. Instead, design your solution to react to important events in real time upon receipt of the webhook notification.

This guide explains how to subscribe to webhooks and contains an explanation and sample payload for each webhook event.

Evaluate the webhooks that are important to your use cases and subscribe to receive information about system events as they occur. These webhooks are primarily intended for asynchronous activities or actions initiated by your end user from outside your ecosystem.

Integrating Webhooks

When an event occurs for which you, as a consumer, have subscribed to webhooks, the MatchMove platform sends an HTTPS POST request containing information about the event to a pre-configured endpoint hosted on a consumer's system.

As a consumer of these webhooks, you are expected to ensure that your system can process the message received as part of the webhooks and respond as expected on certain business use cases.

The webhook messages may also be upgraded periodically, as aligned with the platform upgrade policies.

Webhook types

The platform supports two types of webhook delivery systems:

Additional Metadata

Enhanced webhooks have additional metadata provided in the headers that enable their enhanced capabilities:

Dynamic response handling

The enhanced webhooks will continue to retry sending until an explicit 200 is received from the api consumer's backend host during the attempt period.

You can also choose to dynamically decide to manage the behavior of webhooks and subscriptions by responding with the corresponding HTTP codes as highlighted by the table below:

Content Verification

To ensure that the webhook comes from an authentic source, a signature hash is provided in the HTTP header as a MatchMove-Webhook-Signature field. This safety mechanism should protect against misuse of the webhook address.

The signature is generated via the HMAC SHA256 algorithm using:

• The provided API credential secret will be used as the HMAC key
• The request body is the data

Partners must use the same algorithm to encrypt their responses and match them to the signature received from the webhook header. If both signatures match, the request can be considered valid. Otherwise, the request may be denied.

Refer to the HMAC SHA256 encryption sample codes below:

 
import(
  "crypto/hmac"
  "crypto/sha256"
  "io"
)

func generateHMACSHA256(hmacKey string, requestBody string) string {
  hash := hmac.New(sha256.New, []byte(hmacKey))
  io.WriteString(hash, requestBody)
  return fmt.Sprintf("%x", hash.Sum(nil))
}

 
public function generateHMACSHA256($hmacKey, $requestBody) {
  $hash = hash_hmac('sha256', $requestBody, $hmacKey);
  return $hash;
}

 
import hmac
import hashlib

def generateHMACSHA256(hmacKey, requestBody):
  return hmac.new(
    hmacKey.encode("utf-8"),
    requestBody.encode("utf-8"),
    hashlib.sha256
  )

 
const crypto = require('crypto');

const generateHMACSHA256 = (hmacKey, requestBody) =>
  crypto.createHmac('sha256', hmacKey).update(requestBody);

 
public static String generateHMACSHA256(String hmacKey, String requestBody) {
    try {
        // Initialize HMAC with SHA256
        Mac sha256Hmac = Mac.getInstance("HmacSHA256");
        SecretKeySpec secretKeySpec = new SecretKeySpec(hmacKey.getBytes(StandardCharsets.UTF_8), "HmacSHA256");
        sha256Hmac.init(secretKeySpec);

        // Compute the HMAC
        byte[] hmacData = sha256Hmac.doFinal(requestBody.getBytes(StandardCharsets.UTF_8));

        // Convert byte array to hexadecimal string
        StringBuilder sb = new StringBuilder();
        for (byte b : hmacData) {
            sb.append(String.format("%02x", b));
        }
        return sb.toString();

    } catch (NoSuchAlgorithmException | InvalidKeyException e) {
        throw new RuntimeException("Failed to generate HMACSHA256", e);
    }
}

Configure Webhook Subscriptions

Each webhook category and event has its purpose depending on the use case it is associated with. Subscribing to webhooks eliminates the need to pull updates through the API manually.

Instead, partners can listen and anticipate when an event will occur, be notified, and respond accordingly.

Go to the Subscribe to webhooks section to learn more about subscribing to and managing webhooks.

FAQ

• Do I subscribe to a category or individual events under a category? Consumers can choose which level they want to subscribe to. If they subscribe to a category, then all events under that category will be subscribed to automatically.

• Is there any restriction on the URL to be configured? The URLs must be HTTPS domains. The SSL certificate associated with the domain should support a minimum TLS version of 1.2.

Example of a valid webhook URL: https://example.com/callback/matchmove

Example of invalid webhook URL: http://example.com/callback/matchmove https://example.com:3002/callback/matchmove

• What happens if I configure a URL that doesn't meet the above standards? The platform security controls will not allow webhooks to be triggered if the above rules are not followed.

Webhook-related API

Related Links

• Start your implementation
• Begin technical integration
• Implementation checklist
• Build with Gen AI
• Utilize enumerations