Receive Masnet events in Boomi

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.

Process configuration

1. Create a process that starts with a Boomi web server connector in listen mode (Web Services Server) and publish its URL with TLS on a public DNS name (https, port 443 or 8443). That URL is what you enter in Destination address (https) in Masnet.
2. Boomi can expose the HTTP headers as dynamic document properties. The exact names of those properties are not published here because they could not be verified with the available documentation: run the test event and inspect the document properties in the process trace to identify those of webhook-id, webhook-timestamp and webhook-signature.
3. Add a custom scripting step before any map or conversion, so that the script receives the original body.
4. Store the signing secret as an encrypted process property or protected extension, not in 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 must perform these steps, in this order:

1. Read webhook-id, webhook-timestamp and webhook-signature. Reject if any is missing or if the absolute difference from the current time exceeds 300 seconds.
2. Base64-decode the secret without the whsec_ prefix to obtain the key.
3. Compute HMAC-SHA256 with that key over webhook-id + . + webhook-timestamp + . + the body bytes.
4. Split webhook-signature on spaces; for each v1,<base64> part, compare in constant time with the computed value. One match is enough.

The reference Java implementation, executed against the test vectors of this documentation, is in Java verification.

Response

Answer 200 if the signature is valid. If it is not, return a 401 status; Masnet will retry. If downstream processing is long, decouple it so that you answer within 15 seconds.

Testing with the test event

1. Deploy the process to your Atom.
2. In Masnet, select Test destination and Send test.
3. Check in the process trace that the document arrived with the header Masnet-Event-Type: com.masnet.integration.test.v1.

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: