Receive Masnet events in SAP Integration Suite

Requirements in Masnet

Before configuring the receiving system, prepare the destination in Masnet. The steps are the same for every system.

1. Open Company › Integrations (the Spanish interface labels it Empresa › Integraciones), go to the Destinations tab and select New destination. If the integration has no authorized data yet, Masnet asks you to authorize it first.
2. In Destination address (https) enter the receiver public URL. It must be https, port 443 or 8443 and a public DNS name: user information in the URL, fragments, IP addresses and internal names are not accepted. A query string is allowed; Masnet treats the whole URL as a credential.
3. In Format choose Standard JSON (application/json) or Structured CloudEvents (application/cloudevents+json). The event content is the same; see Webhooks.
4. Select Create destination. Masnet shows the signing secret (whsec_…) only once. Store it immediately in the receiver secret store; it cannot be read again.
5. Select Test destination and then Send test. The integration is activated only after a successful test; then use Activate destination.

iFlow configuration

1. Create an iFlow and use an HTTPS sender adapter.
2. In the address parameter enter a path of your own, for example /masnet/events. The runtime URL has the form https://<runtime host>/http/masnet/events; that full URL is what you enter in Destination address (https) in Masnet.
3. In the authorization parameter choose an SAP method compatible with one of the methods Masnet can send (Basic, Bearer, OAuth 2.0 client credentials or mTLS) and configure the same method in the Masnet destination credentials. The signature is always sent, with any method.
4. Leave CSRF protection disabled: Masnet does not fetch a token beforehand. Confirm the behavior in the documentation of your version.
5. Add a Script step immediately after the adapter, before any converter or mapping. Paste the script from the next section.
6. Load the signing secret as an SAP secure parameter and assign it to the message property webhook_secret before the script. Do not write it inside the script.

Signature verification

The signature is v1, followed by base64(HMAC-SHA256) computed with the binary key obtained by base64-decoding what follows whsec_, over the bytes webhook-id + . + webhook-timestamp + . + the exact body. Always verify over the received bytes, before parsing the JSON.

The script reads webhook-id, webhook-timestamp and webhook-signature from the message headers and the body as byte[]. It rejects events more than 5 minutes off and accepts any of the signatures in the header.

import com.sap.gateway.ip.core.customdev.util.Message
import javax.crypto.Mac
import javax.crypto.spec.SecretKeySpec
import java.security.MessageDigest

// Script step of the iFlow. The secret is read from a Secure Parameter alias or property, never hardcoded.
Message processData(Message message) {
    def headers = message.getHeaders()
    String id = headers.get('webhook-id')
    String timestamp = headers.get('webhook-timestamp')
    String signatures = headers.get('webhook-signature')
    String secret = message.getProperty('webhook_secret')
    byte[] body = message.getBody(byte[])          // raw bytes, before any JSON mapping

    boolean ok = false
    if (id && timestamp ==~ /\d+/ && signatures && Math.abs(System.currentTimeMillis().intdiv(1000) - Long.parseLong(timestamp)) <= 300) {
        byte[] key = Base64.decoder.decode(secret.replaceFirst('^whsec_', ''))
        Mac mac = Mac.getInstance('HmacSHA256')
        mac.init(new SecretKeySpec(key, 'HmacSHA256'))
        mac.update("${id}.${timestamp}.".getBytes('UTF-8'))
        byte[] expected = mac.doFinal(body)
        // Two signatures separated by a space while the secret is rotating; any match is valid.
        ok = signatures.split(' ').any { part ->
            def pair = part.split(',', 2)
            if (pair.length != 2 || pair[0] != 'v1') return false
            try {
                return MessageDigest.isEqual(Base64.decoder.decode(pair[1]), expected)
            } catch (IllegalArgumentException ignored) {
                return false                               // malformed entry: ignore it and try the next one
            }
        }
    }
    if (!ok) throw new SecurityException('Invalid Masnet webhook signature')   // the iFlow answers with an error status
    message.setProperty('signature_verified', 'true')
    return message
}

Response

If the script ends without an exception, the iFlow answers with success (2xx). If it throws SecurityException, the iFlow answers with an error status and Masnet retries; this is expected for an invalid signature. Keep downstream processing decoupled (for example, with the messaging mechanism of your iFlow) so that you answer well within 15 seconds.

Testing with the test event

1. Deploy the iFlow.
2. In Masnet, select Test destination and Send test.
3. Check in the SAP message monitor that the message arrived with Masnet-Event-Type: com.masnet.integration.test.v1 and that signature_verified is true.
4. In Masnet, the result shows the response code and the measured times.

Operation: duplicates and ordering

• Idempotency. webhook-id identifies the event and is kept across retries and redeliveries. Record the identifiers already processed and discard repeats with a 2xx response.
• Ordering. Each resource (subject) carries an increasing sequence. Discard an event whose sequence is lower than or equal to the last one applied for that subject. Events of different resources have no order between them.
• Retries. Masnet retries any non-2xx response for up to 72 hours; the full schedule is in Webhooks.
• Secret rotation. When rotating with overlap, the previous secret stays valid for 24 hours and webhook-signature carries two v1,… signatures separated by a space. Accept the event if either one matches.

Troubleshooting

Masnet records the response code of each attempt in the delivery history. These are the effects of each receiver response: