Receive Masnet events in n8n

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.

Workflow configuration

1. Add a Webhook node with HTTP Method POST and a Path of your own. Use the node Production URL (not the test one) in Destination address (https) in Masnet; the workflow must be active.
2. In Options, add Raw Body. Per the n8n documentation, it makes the node receive the data in a raw format.
3. In Respond, choose Immediately to answer right away, or Using 'Respond to Webhook' Node if you must answer 401 for an invalid signature.
4. Store the signing secret as an n8n environment variable or credential, not inside the workflow.

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.

Add a Code node after the Webhook. The example is illustrative: the name of the binary property with the body, the way to read environment variables and the permission to load the crypto module depend on your version and your n8n configuration; confirm them with the test event.

// Code node ("Run Once for All Items"), illustrative.
// Requires the Webhook node option "Raw Body" and permission to load the built-in module "crypto".
const crypto = require('crypto');
const item = $input.first();
const headers = item.json.headers;
const raw = await this.helpers.getBinaryDataBuffer(0, 'data'); // confirm the binary property name in the node output
const secret = $env.MASNET_WEBHOOK_SECRET;                      // keep the secret outside the workflow

const id = headers['webhook-id'];
const ts = headers['webhook-timestamp'];
const key = Buffer.from(secret.replace(/^whsec_/, ''), 'base64');
const expected = crypto.createHmac('sha256', key).update(id + '.' + ts + '.').update(raw).digest();
const fresh = Math.abs(Date.now() / 1000 - Number(ts)) <= 300;
const valid = fresh && String(headers['webhook-signature']).split(' ').some((part) => {
  const [version, value] = part.split(',');
  const given = Buffer.from(value || '', 'base64');
  return version === 'v1' && given.length === expected.length && crypto.timingSafeEqual(given, expected);
});
if (!valid) throw new Error('Invalid Masnet webhook signature');
return [{ json: { verified: true, eventId: id } }];

If your installation cannot obtain the original bytes, do not verify by rebuilding the JSON: reserializing can change the bytes. Use instead a service of your own with the Node.js guide.

Response

With Immediately, n8n answers before running the rest; a failed verification is not reflected in the response. To return 401 for an invalid signature use Using 'Respond to Webhook' Node. Always finish within 15 seconds.

Testing with the test event

1. Activate the workflow.
2. In Masnet, select Test destination and Send test.
3. In the n8n executions, check that the Code node ends without error.

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: