Webhooks v2

Webhooks are notifications triggered upon event changes in the Attrus platform — for both customer and transaction events. They are delivered to the URL you register with us.

All webhook management routes live under /api/v2/notifications/ and require a valid JWT (same authentication as the rest of the API). You can register one or more endpoints, choose which event types each endpoint receives, and manage delivery history through the API.

When your server is unavailable, Attrus retries delivery automatically with increasing intervals (up to 10 attempts).

IP allowlist

Attrus webhook requests originate from a fixed set of IP addresses per environment. To avoid disruptions, configure your firewall to allow the IPs below.

Sandbox

54.83.243.64

Production

35.174.148.67
174.138.54.115

For questions or help with the configuration, contact support@attrus.com.

Delivery payload format

Every webhook delivery sends a JSON body with the following structure:

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "type": "identified",
  "data": {
    "transaction_id": "173e30f4-9956-4e86-8fc0-d27b125a8678"
  }
}

{
  "notification": {
    "type": "identified",
    "transaction_id": "173e30f4-9956-4e86-8fc0-d27b125a8678",
    "secret": "your_secret_value"
  }
}

Verifying webhook signatures

Every delivery includes an HMAC-SHA256 signature in the attrus-signature request header:

attrus-signature: t=1719494400,v1=abc123...

During a secret rotation, the header may also include v0= with a signature computed using the previous secret (valid for 24 hours):

attrus-signature: t=1719494400,v1=new_sig...,v0=old_sig...

To verify a delivery:

1. Read the raw request body (before JSON parsing).
2. Parse the header: extract t (Unix timestamp), v1, and optionally v0.
3. Compute expected = HMAC-SHA256(secret, "{t}.{raw_body}") as a lowercase hex string.
4. Compare expected with v1 using a constant-time comparison. If they differ and v0 is present, repeat step 3 with your previous secret and compare with v0.
5. Optionally reject requests whose timestamp is too far from your server clock.

The secret is returned when you create an endpoint or rotate the secret.

Creating a webhook endpoint

Register a URL to receive events. You can create multiple endpoints (for example, separate URLs for sandbox and production handlers, or different event filters per URL).

curl -X POST "{{API_ORIGIN}}/api/v2/notifications/endpoints" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -d '{
  "url": "https://your-server.com/webhooks",
  "enabled_events": ["*"]
}'

{
  "data": {
    "id": "endpoint-uuid-123",
    "company_id": "your-company-uuid",
    "url": "https://your-server.com/webhooks",
    "status": "active",
    "enabled_events": ["*"],
    "delivery_mode": "parallel",
    "event_payload_type": "snapshot",
    "inject_secret_in_body": false,
    "event_mapping": null,
    "wrap_in_notification": false,
    "max_concurrency": 10,
    "secret": "e3b0c44298fc1c149afbf4c8996fb924...",
    "previous_secret": null,
    "previous_secret_expires_at": null,
    "inserted_at": "2026-06-26T10:00:00Z",
    "updated_at": "2026-06-26T10:00:00Z"
  }
}

Store the secret securely — it is used to verify incoming deliveries. The secret is a 64-character lowercase hex string and is included in responses to create, show, and rotate secret requests.

HTTP Request

POST /api/v2/notifications/endpoints

Body Parameters

Retrieving a webhook endpoint

curl -X GET "{{API_ORIGIN}}/api/v2/notifications/endpoints/endpoint-uuid-123" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

{
  "data": {
    "id": "endpoint-uuid-123",
    "company_id": "your-company-uuid",
    "url": "https://your-server.com/webhooks",
    "status": "active",
    "enabled_events": ["*"],
    "delivery_mode": "parallel",
    "event_payload_type": "snapshot",
    "inject_secret_in_body": false,
    "event_mapping": null,
    "wrap_in_notification": false,
    "max_concurrency": 10,
    "secret": "e3b0c44298fc1c149afbf4c8996fb924...",
    "previous_secret": null,
    "previous_secret_expires_at": null,
    "inserted_at": "2026-06-26T10:00:00Z",
    "updated_at": "2026-06-26T10:00:00Z"
  }
}

HTTP Request

GET /api/v2/notifications/endpoints/:id

Path Parameters

Updating a webhook endpoint

curl -X PUT "{{API_ORIGIN}}/api/v2/notifications/endpoints/endpoint-uuid-123" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -d '{
  "enabled_events": ["identified", "payment_approved", "payment_failed"],
  "max_concurrency": 5
}'

{
  "data": {
    "id": "endpoint-uuid-123",
    "company_id": "your-company-uuid",
    "url": "https://your-server.com/webhooks",
    "status": "active",
    "enabled_events": ["identified", "payment_approved", "payment_failed"],
    "delivery_mode": "parallel",
    "event_payload_type": "snapshot",
    "inject_secret_in_body": false,
    "event_mapping": null,
    "wrap_in_notification": false,
    "max_concurrency": 5,
    "secret": "e3b0c44298fc1c149afbf4c8996fb924...",
    "previous_secret": null,
    "previous_secret_expires_at": null,
    "inserted_at": "2026-06-26T10:00:00Z",
    "updated_at": "2026-06-26T11:30:00Z"
  }
}

HTTP Request

PUT /api/v2/notifications/endpoints/:id

Path Parameters

Body Parameters

Any field from creating an endpoint can be updated (including url). Omit fields you do not want to change.

Deleting a webhook endpoint

Disables a single endpoint (soft delete — status becomes disabled).

curl -X DELETE "{{API_ORIGIN}}/api/v2/notifications/endpoints/endpoint-uuid-123" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

{
  "data": {
    "id": "endpoint-uuid-123",
    "status": "disabled"
  }
}

HTTP Request

DELETE /api/v2/notifications/endpoints/:id

Path Parameters

Disabling all webhook endpoints

Stops delivery on every active endpoint for your account.

curl -X DELETE "{{API_ORIGIN}}/api/v2/notifications/endpoints" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

{
  "data": "ok"
}

HTTP Request

DELETE /api/v2/notifications/endpoints

Rotating the endpoint secret

Generates a new signing secret. The previous secret remains valid for 24 hours (signatures may include both v1 and v0 during this window), giving you time to update your verification logic without missing deliveries.

curl -X POST "{{API_ORIGIN}}/api/v2/notifications/endpoints/endpoint-uuid-123/rotate_secret" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

{
  "data": {
    "id": "endpoint-uuid-123",
    "secret": "d7a8fbb307d7809469ca9abcb0082e4f...",
    "previous_secret": "e3b0c44298fc1c149afbf4c8996fb924...",
    "previous_secret_expires_at": "2026-06-27T10:00:00Z"
  }
}

HTTP Request

POST /api/v2/notifications/endpoints/:id/rotate_secret

Path Parameters

Listing webhook events

Returns delivery records for your account. Supports cursor pagination and filters for debugging and reconciliation.

Example: /api/v2/notifications/events?last_id=a5c69e9e-8d84-4b0b-9af8-dcfb5be35093&per_page=20&order_by=desc returns the next page after that event ID. With order_by=desc (default), that means older events.

curl -X GET "{{API_ORIGIN}}/api/v2/notifications/events?status=failed&type=payment_failed&from=2026-06-01&to=2026-06-30" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

{
  "data": [
    {
      "id": "event-uuid-1",
      "event_id": "original-event-uuid-1",
      "endpoint_id": "endpoint-uuid-123",
      "type": "payment_failed",
      "status": "failed",
      "payload": {
        "transaction_id": "173e30f4-9956-4e86-8fc0-d27b125a8678"
      },
      "event_created_at": "2026-06-26T10:00:00Z",
      "inserted_at": "2026-06-26T10:00:01Z"
    }
  ]
}

HTTP Request

GET /api/v2/notifications/events

Query Parameters

Retrieving a webhook event

Returns a single event with its full delivery attempt history.

curl -X GET "{{API_ORIGIN}}/api/v2/notifications/events/event-uuid-1" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

{
  "data": {
    "id": "event-uuid-1",
    "event_id": "original-event-uuid-1",
    "endpoint_id": "endpoint-uuid-123",
    "company_id": "your-company-uuid",
    "type": "payment_failed",
    "status": "failed",
    "payload": {
      "transaction_id": "173e30f4-9956-4e86-8fc0-d27b125a8678"
    },
    "event_created_at": "2026-06-26T10:00:00Z",
    "inserted_at": "2026-06-26T10:00:01Z",
    "attempts": [
      {
        "id": "attempt-uuid-1",
        "attempt_number": 1,
        "http_status": 401,
        "response_body": "Unauthorized",
        "inserted_at": "2026-06-26T10:00:02Z"
      }
    ]
  }
}

HTTP Request

GET /api/v2/notifications/events/:id

Path Parameters

Acknowledging a webhook event

Marks an event as successfully processed on your side. Use this when your server was temporarily unavailable but you retrieved and handled the event through the API.

curl -X PUT "{{API_ORIGIN}}/api/v2/notifications/events/event-uuid-1/acknowledge" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

{
  "data": {
    "id": "event-uuid-1",
    "status": "succeeded"
  }
}

HTTP Request

PUT /api/v2/notifications/events/:id/acknowledge

Path Parameters

Retrying a webhook event

Re-enqueues delivery for a failed event. Returns 422 if the event has already succeeded.

curl -X POST "{{API_ORIGIN}}/api/v2/notifications/events/event-uuid-1/retry" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

{
  "message": "retry enqueued"
}

HTTP Request

POST /api/v2/notifications/events/:id/retry

Path Parameters

Webhook event payloads

The sections below describe every event type Attrus can send. All examples use the default v2 delivery format with id, type, and data fields.

Webhooks for transactions

Identified transaction

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "type": "identified",
  "data": {
    "transaction_id": "173e30f4-9956-4e86-8fc0-d27b125a8678"
  }
}

We always send webhook notifications for all transactions whenever there is a status change. This webhook will always be the first notification you receive — assuming everything goes as expected. It is triggered when the incoming funds are received in the Attrus bank account created exclusively for your use, or when there is sufficient available balance to initiate a transaction such as payouts or conversions between internal accounts.

Exchange created for transaction

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "type": "exchange_created",
  "data": {
    "exchange_id": "some_uuid",
    "transaction_ids": [
      "transaction-id-a",
      "transaction-id-b"
    ]
  }
}

If the transaction involves a currency conversion, this webhook will be triggered after the previous one (type: identified). It will be sent either once the exchange has been successfully created by our operations team, or automatically right after the identified notification if you have automatic exchange enabled.

Note that a single exchange can be associated with multiple transactions if they share the same subject and destination account. For this reason, you will receive a list of transaction IDs in the transaction_ids field.

Wire created

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "type": "wire_created",
  "data": {
    "wire_id": "some_uuid",
    "transaction_ids": [
      "transaction-id-a",
      "transaction-id-b"
    ]
  }
}

Once the funds leave Attrus environment to complete a transaction — such as a payout or a requested settlement — this webhook will be triggered to notify you that the wire has been completed. In short, it means the funds have already been sent either to your customer's bank account or to your international bank account.

Note that a single wire transfer can be associated with multiple transactions if they share the same subject and destination account. For this reason, you will receive a list of transaction IDs in the transaction_ids field.

Example: You need to send money to your customer and create two transactions using the same destination bank account. Instead of sending the funds separately, we will group them and send a single wire with the total amount of both transactions combined.

Approved card transaction

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "type": "payment_approved",
  "data": {
    "transaction_id": "bfb7a294-89ad-4a9e-a221-5e9c499a05f0"
  }
}

We also have specific webhooks for card related transactions. This webhook will be triggered when a card payment has been approved for a card transaction:

Parameters

Reproved card transaction

If a card payment is not approved, the following webhook will be sent.

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "type": "payment_failed",
  "data": {
    "transaction_id": "bfb7a294-89ad-4a9e-a221-5e9c499a05f0"
  }
}

Parameters

Request for wire correction

When Attrus can't process a payment due to receiver account information errors, such as incorrect branch or account number, the API will send a wire_waiting_correction. To correct the bank account details, you must send a request to update it using the endpoint in the sequence below.

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "type": "wire_waiting_correction",
  "data": {
    "error_code": "AC03",
    "error_description": "Creditor account number invalid or missing",
    "bank_account_owner_id": "person-UUID",
    "bank_account_id": "bank-account-UUID",
    "transaction_ids": [
      "transaction-UUID"
    ],
    "wire_id": "wire-UUID"
  }
}

Error Codes

Sending the correct bank account details for wire

curl -X PUT "{{API_BASE_URL}}/wires/:id/update_bank_account" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -d '{
  "bank_account": {
    "currency": "BRL",
    "bank": {"code": "260","name": "Nu Pagamentos S.A."},
    "branch_number": "1",
    "account_number": "36725089",
    "owner_document_number": "Person name",
    "owner_name": "Person name",
    "branch_country": "BR",
    "account_type": "conta-corrente"
  }
}'

Once you get the correct bank account information from the customer you must send a request to update it using the following endpoint, so the API will then try again. If it succeeds, the API sends the wire_created webhook.

{
  "currency": "BRL",
  "id": "51ca5a65-bbd2-433d-8527-1cb36bf4a1c2",
  "inserted_at": "2025-07-10T18:39:43.580056",
  "status": "waiting_confirmation",
  "to_bank_account": {
    "aba": null,
    "account_number": "456",
    "account_type": "conta-corrente",
    "bank": {
      "code": "012",
      "country": "BRA",
      "id": "04bf9dc2-f189-4a1f-929d-5478def064e9",
      "ispb": "04866275",
      "name": "Banco Inbursa S.A.",
      "swift": null
    },
    "branch_country": "BRA",
    "branch_number": "8221",
    "company": {
      "company_name": "Subject",
      "document_number": "67645727390",
      "document_type": "cpf",
      "fiscal_country": "BRA",
      "id": "31288cc8-e106-4aec-8437-85758ba671c0",
      "phone_number": null,
      "social_name": "Subject"
    },
    "currency": "BRL",
    "iban": null,
    "id": "79247afc-b15d-441c-af72-08f2013fd58e",
    "intermediary_bank_account": null,
    "nickname": null,
    "owner_document_number": "67645727390",
    "owner_document_type": null,
    "owner_name": "Subject",
    "pix_info": null,
    "routing_number": null
  },
  "unretryable": false,
  "value": "500.0"
}

HTTP Request

PUT /api/v1/wires/:id/update_bank_account

Account Type Values

Webhooks for subscriptions

We always send webhook notifications for all subscriptions whenever there is a status change. This section describes the webhooks for subscriptions.

Subscription QR Code generated

This notification is sent when an automatic PIX subscription has a QR Code ready for customer authorization.

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "type": "subscription_qr_code_generated",
  "data": {
    "subscription": {
      "id": "e97e7ad9-3cfc-4701-8a4f-77eaa9402b35",
      "status": "pending",
      "subject_id": "e0e34575-bee4-423d-a989-cfd525b965cf",
      "qr_code": "00020126580014br.gov.bcb.pix0136123e4567-e89b-12d3-a456-426614174000520400005303986540510.005802BR5913FACILITA PAY6008BRASILIA62070503***63041D3D"
    }
  }
}

Subscription activated

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "type": "subscription_activated",
  "data": {
    "subscription": {
      "id": "e97e7ad9-3cfc-4701-8a4f-77eaa9402b35",
      "status": "active",
      "subject_id": "e0e34575-bee4-423d-a989-cfd525b965cf"
    }
  }
}

This notification is sent when the subscription is activated, meaning that the first invoice has been successfully processed and the subscription is now active.

Subscription canceled

This webhook is triggered whenever a subscription is canceled, either by the merchant via API or by the payer. The field canceled_by_payer indicates whether the cancellation was initiated by the payer (true) or by the merchant (false).

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "type": "subscription_canceled",
  "data": {
    "subscription": {
      "canceled_by_payer": false,
      "canceled_reason": "some reason",
      "id": "7de0dc6f-f514-4401-84f3-ff19183e6b92",
      "status": "canceled",
      "subject_id": "76d5aea7-f532-47be-9cfb-b1f615c7bc84"
    }
  }
}

Subscription is complete

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "type": "subscription_completed",
  "data": {
    "subscription": {
      "id": "7de0dc6f-f514-4401-84f3-ff19183e6b92",
      "status": "completed",
      "subject_id": "76d5aea7-f532-47be-9cfb-b1f615c7bc84"
    }
  }
}

This webhook is triggered when a subscription completes its full lifecycle — meaning all cycles have been processed and every related invoice has been successfully paid.

Invoice paid

This notification is sent when an invoice related to a subscription is paid.

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "type": "invoice_paid",
  "data": {
    "invoice": {
      "id": "d5dbfff5-7391-447b-a642-a57af80b09db",
      "status": "paid",
      "subject_id": "7c6afdd6-eb4b-4113-93c6-95be304ea9cc",
      "subscription_id": "991740dd-d1d3-4f80-81ad-7062388aaedc"
    }
  }
}

Non-identified Bank Transaction

When an unregistered customer makes a bank transfer to the bank account we opened for you, we will send a notification with the customer's information. You must register this person or company to access the funds from that transaction. If you do not complete the registration, the payment will be refunded within two business days.

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "type": "non_identified_bank_transaction",
  "data": {
    "bank_transaction": {
      "id": "uuid-of-the-transaction",
      "value": "5000.0",
      "currency": "BRL",
      "movement_date": "2024-01-05",
      "bank_account_id": "uuid-of-the-bank-account",
      "paid_at": "2024-01-05T06:38:56.367425",
      "spei_concepto_de_pago": "only for Mexican transactions, when informed by payer",
      "subject": {
        "document_number": "93111817067",
        "document_type": "cpf",
        "name": "António Elias",
        "bank_account": {
          "bank": "033",
          "branch_number": "0001",
          "account_number": "000001",
          "account_type": "conta-corrente"
        }
      }
    }
  }
}

Parameters

Once you register this individual or company, we will send you a notification with type: identified and the transaction id. The funds will then be made available in your account.

Webhooks related to customers

Subject approved

This webhook notifies when a person or company registration has been approved:

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "type": "subject_approved",
  "data": {
    "subject_id": "UUID"
  }
}

Subject reproved

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "type": "subject_reproved",
  "data": {
    "subject_id": "someid",
    "reason": "Some reason for not being approved",
    "items": ["proof_of_address_missing"]
  }
}

This following webhook notifies that a person or company registration has been rejected, as well as the reason for the reproval. This webhook is sent whenever the transaction limit for that person/company is reached, so its status automatically goes to reproved. The API also sends it if the backoffice rejects one or more of the provided documents.

The address proof document is not valid.

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "type": "subject_reproved",
  "data": {
    "subject_id": "UUID",
    "items": ["proof_of_address_rejected"]
  }
}

The provided tax declaration is too old.

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "type": "subject_reproved",
  "data": {
    "subject_id": "UUID",
    "items": ["old_tax_declaration"]
  }
}

Customer´s transactioned amount and provided tax declaration values mismatch.

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "type": "subject_reproved",
  "data": {
    "subject_id": "UUID",
    "items": ["tax_declaration_insufficient"]
  }
}

Webhooks for refunded payments

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "type": "payment_refunded",
  "data": {
    "transaction_id": "UUID"
  }
}

If you enable the feature of not accepting payments from third parties, you will receive this webhook to let you know that a payment was refunded. If a dynamic Pix QR code was paid from an account whose ownership is different from the specified subject_id in the transaction, we will automatically refund the payer and send the following webhook:

Webhooks for document requests

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "type": "document_required",
  "data": {
    "subject_id": "UUID",
    "required_documents": ["revenue_tax_declaration", "proof_of_address"]
  }
}

This webhook requests additional documents from a customer without changing their approval status.

Webhooks for expired payments

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "type": "payment_expired",
  "data": {
    "transaction_id": "UUID"
  }
}

The payment_expired webhook is sent when:

• A Dynamic PIX QR code payment is not paid by the customer within the specified date, or
• A Dynamic CLABE transaction is not paid within the expiration period